<!DOCTYPE html>
<!-- saved from url=(0076)http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#introduction -->
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.2">
<meta name="author" content="Stuart Douglas">
<title>Undertow</title>
<link rel="stylesheet" href="./Undertow_files/css">
<style>
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Remove the comments around the @import statement below when using this as a custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
[hidden],template{display:none}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
body{margin:0}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}
input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*:before,*:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
#map_canvas img,#map_canvas embed,#map_canvas object,.map_canvas img,.map_canvas embed,.map_canvas object{max-width:none!important}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
.antialiased,body{-webkit-font-smoothing:antialiased}
img{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
p.lead,.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{font-size:1.21875em;line-height:1.6}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #ddddd8;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ul.no-bullet{list-style:none}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite:before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media only screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7;font-weight:bold}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix:before,.clearfix:after,.float-group:before,.float-group:after{content:" ";display:table}
.clearfix:after,.float-group:after{clear:both}
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
.keyseq{color:rgba(51,51,51,.8)}
kbd{display:inline-block;color:rgba(0,0,0,.8);font-size:.75em;line-height:1.4;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:-.15em .15em 0 .15em;padding:.2em .6em .2em .5em;vertical-align:middle;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menu{color:rgba(0,0,0,.8)}
b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
b.button:before{content:"[";padding:0 3px 0 2px}
b.button:after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header:before,#header:after,#content:before,#content:after,#footnotes:before,#footnotes:after,#footer:before,#footer:after{content:" ";display:table}
#header:after,#content:after,#footnotes:after,#footer:after{clear:both}
#content{margin-top:1.25em}
#content:before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #ddddd8}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #ddddd8;padding-bottom:8px}
#header .details{border-bottom:1px solid #ddddd8;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span:before{content:"\00a0\2013\00a0"}
#header .details br+span.author:before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark:before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber:after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #ddddd8;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #efefed;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media only screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #efefed;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #efefed;left:auto;right:0}}@media only screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
.sect1{padding-bottom:.625em}
@media only screen and (min-width:768px){.sect1{padding-bottom:1.25em}}.sect1+.sect1{border-top:1px solid #efefed}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor:before,h2>a.anchor:before,h3>a.anchor:before,#toctitle>a.anchor:before,.sidebarblock>.content>.title>a.anchor:before,h4>a.anchor:before,h5>a.anchor:before,h6>a.anchor:before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
.paragraph.lead>p,#preamble>.sectionbody>.paragraph:first-of-type p{color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;padding:1em;font-size:.8125em}
.literalblock pre.nowrap,.literalblock pre[class].nowrap,.listingblock pre.nowrap,.listingblock pre[class].nowrap{overflow-x:auto;white-space:pre;word-wrap:normal}
@media only screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}@media only screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.listingblock code[data-lang]:before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
.listingblock:hover code[data-lang]:before{display:block}
.listingblock.terminal pre .command:before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt]):before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #ddddd8}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock blockquote p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote:before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.5em;margin-right:.5ex;text-align:right}
.quoteblock .quoteblock{margin-left:0;margin-right:0;padding:.5em 0;border-left:3px solid rgba(0,0,0,.6)}
.quoteblock .quoteblock blockquote{padding:0 0 0 .75em}
.quoteblock .quoteblock blockquote:before{display:none}
.verseblock{margin:0 1em 1.25em 1em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.05em;color:rgba(0,0,0,.6)}
.quoteblock.abstract{margin:0 0 1.25em 0;display:block}
.quoteblock.abstract blockquote,.quoteblock.abstract blockquote p{text-align:left;word-spacing:0}
.quoteblock.abstract blockquote:before,.quoteblock.abstract blockquote p:first-of-type:before{display:none}
table.tableblock{max-width:100%;border-collapse:separate}
table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
table.spread{width:100%}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0}
table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0}
table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0}
table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0}
table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0}
table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0}
table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot{border-width:1px 0}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none}
ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px}
ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
ul.inline>li>*{display:block}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1{padding-right:.75em;font-weight:bold}
td.hdlist1,td.hdlist2{vertical-align:top}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist>table tr>td:first-of-type{padding:0 .75em;line-height:1}
.colist>table tr>td:last-of-type{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
.imageblock.right,.imageblock[style*="float: right"]{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none}
span.footnote,span.footnoteref{vertical-align:super;font-size:.875em}
span.footnote a,span.footnoteref a{text-decoration:none}
span.footnote a:active,span.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em 0;border-width:1px 0 0 0}
#footnotes .footnote{padding:0 .375em;line-height:1.3;font-size:.875em;margin-left:1.2em;text-indent:-1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]:after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
h1,h2{letter-spacing:-.01em}
dt,th.tableblock,td.content{text-rendering:optimizeLegibility}
p,td.content{letter-spacing:-.01em}
p strong,td.content strong{letter-spacing:-.005em}
p,blockquote,dt,td.content{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@media print{@page{margin:1.25cm .75cm}
*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare):after,a[href^="https:"]:not(.bare):after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]:after{content:" (" attr(title) ")"}
pre,blockquote,tr,img{page-break-inside:avoid}
thead{display:table-header-group}
img{max-width:100%!important}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #ddddd8!important;padding-bottom:0!important}
.sect1{padding-bottom:0!important}
.sect1+.sect1{border:0!important}
#header>h1:first-child{margin-top:1.25rem}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em 0}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span:before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]:before{display:block}
#footer{background:none!important;padding:0 .9375em}
#footer-text{color:rgba(0,0,0,.6)!important;font-size:.9em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
</style>
<link rel="stylesheet" href="./Undertow_files/font-awesome.min.css">
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
.CodeRay .line-numbers strong{font-weight: normal}
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
table.CodeRay td{vertical-align: top}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
table.CodeRay td.code{padding:0 0 0 .5em}
table.CodeRay td.code>pre{padding:0}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#00}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body class="article toc2 toc-left" style="position: static;">
<div id="header">
<h1>Undertow</h1>
<div class="details">
<span id="author" class="author">Stuart Douglas</span><br>
<span id="email" class="email">&lt;<a href="mailto:sdouglas@redhat.com">sdouglas@redhat.com</a>&gt;</span><br>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#introduction" style="">Introduction</a>
<ul class="sectlevel2">
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#introduction-to-undertow" style="">Introduction to Undertow</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#getting-undertow" style="">Getting Undertow</a></li>
</ul>
</li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-core">Undertow Core</a>
<ul class="sectlevel2">
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#bootstrapping-undertow" style="">Bootstrapping Undertow</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#architecture-overview" style="">Architecture Overview</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#listeners-2" style="">Listeners</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#built-in-handlers" style="">Built in Handlers</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-handler-authors-guide" style="">Undertow Handler Authors Guide</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-request-lifecyle" style="">Undertow Request Lifecyle</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#error-handling">Error Handling</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#security" style="">Security</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#predicates-attributes-and-handlers" style="">Predicates Attributes and Handlers</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#reverse-proxy" style="">Reverse Proxy</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#websockets" style="">Websockets</a></li>
</ul>
</li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-servlet">Undertow Servlet</a>
<ul class="sectlevel2">
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#creating-a-servlet-deployment" style="">Creating a Servlet Deployment</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#servlet-extensions" style="">Servlet Extensions</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#using-non-blocking-handlers-with-servlet" style="">Using non-blocking handlers with servlet</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#servlet-security">Servlet Security</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#advanced-servlet-use-cases" style="">Advanced Servlet Use Cases</a></li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#jsp" style="">JSP</a></li>
</ul>
</li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-js" style="">Undertow.js</a>
<ul class="sectlevel2">
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-js-2">Undertow.js</a></li>
</ul>
</li>
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#faq">FAQ</a>
<ul class="sectlevel2">
<li><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-faq">Undertow FAQ</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="introduction"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#introduction"></a>Introduction</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="introduction-to-undertow"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#introduction-to-undertow"></a>Introduction to Undertow</h3>
<div class="paragraph">
<p>Undertow is a web server designed to be used for both blocking and non-blocking tasks. Some of its main
features are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>High Performance</p>
</li>
<li>
<p>Embeddable</p>
</li>
<li>
<p>Servlet 3.1</p>
</li>
<li>
<p>Web Sockets</p>
</li>
<li>
<p>Reverse Proxy</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>There and two main ways that Undertow can be used, either by directly embedding it in your code, or as part of the
<a href="http://www.wildfly.org/">Wildfly Application Server</a>. This guide mostly focuses on the embedded API’s, although a lot
of the content is still relevant if you are using Wildfly, it is just that the relevant functionality will generally
be exposed via XML configuration rather than programatic configuration.</p>
</div>
<div class="paragraph">
<p>The documentation is broken up into two parts, the first part focuses on Undertow code, while the second focuses on
Servlet.</p>
</div>
</div>
<div class="sect2">
<h3 id="getting-undertow"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#getting-undertow"></a>Getting Undertow</h3>
<div class="paragraph">
<p>There are a few ways to get Undertow.</p>
</div>
<div class="sect3">
<h4 id="wildfly"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#wildfly"></a>Wildfly</h4>
<div class="paragraph">
<p>Since version 8.0 Undertow has been the web server component of <a href="http://wildfly.org/">Wildfly</a>. If you are using Wildfly
then you already have Undertow.</p>
</div>
</div>
<div class="sect3">
<h4 id="maven"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#maven"></a>Maven</h4>
<div class="paragraph">
<p>Undertow is built using maven, and is synced to maven central. Undertow provides three seperate artifacts:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Core</dt>
<dd>
<p>Undertow core, which provides support for non blocking handlers and web sockets</p>
</dd>
<dt class="hdlist1">Servlet</dt>
<dd>
<p>Support for Servlet 3.1</p>
</dd>
<dt class="hdlist1">Websockets JSR</dt>
<dd>
<p>Support for the <em>Java API for Websockets (JSR-356)</em> standard</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>In order to use Undertow in your maven projects just include the following section in your pom.xml, and set the <code>undertow.version</code>
property to whatever version of Undertow you wish to use. Only the core artifact is required, if you are not using
Servlet or JSR-356 then those artifacts are not required.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
        <span class="tag">&lt;groupId&gt;</span>io.undertow<span class="tag">&lt;/groupId&gt;</span>
        <span class="tag">&lt;artifactId&gt;</span>undertow-core<span class="tag">&lt;/artifactId&gt;</span>
        <span class="tag">&lt;version&gt;</span>${undertow.version}<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span>
<span class="tag">&lt;dependency&gt;</span>
        <span class="tag">&lt;groupId&gt;</span>io.undertow<span class="tag">&lt;/groupId&gt;</span>
        <span class="tag">&lt;artifactId&gt;</span>undertow-servlet<span class="tag">&lt;/artifactId&gt;</span>
        <span class="tag">&lt;version&gt;</span>${undertow.version}<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span>
<span class="tag">&lt;dependency&gt;</span>
        <span class="tag">&lt;groupId&gt;</span>io.undertow<span class="tag">&lt;/groupId&gt;</span>
        <span class="tag">&lt;artifactId&gt;</span>undertow-websockets-jsr<span class="tag">&lt;/artifactId&gt;</span>
        <span class="tag">&lt;version&gt;</span>${undertow.version}<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="direct-download"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#direct-download"></a>Direct Download</h4>
<div class="paragraph">
<p>Undertow can also be directly downloaded from the <a href="http://mvnrepository.com/search?q=io.undertow">maven repository</a>.</p>
</div>
<div class="paragraph">
<p>Undertow depends on <a href="http://xnio.jboss.org/">XNIO</a> and <a href="https://github.com/jboss-logging/jboss-logging">JBoss Logging</a>,
which will need to be downloaded as well.</p>
</div>
</div>
<div class="sect3">
<h4 id="build-it-yourself"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#build-it-yourself"></a>Build it yourself</h4>
<div class="paragraph">
<p>In order to get the most up to date code you can build Undertow yourself.</p>
</div>
<div class="paragraph">
<p><strong>Prerequisites</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>JDK7 or higher</p>
</li>
<li>
<p>Maven 3.1</p>
</li>
<li>
<p>git</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Building Undertow is easy, just follow these steps:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Configure Maven</dt>
<dd>
<p>Follow the instructions <a href="https://developer.jboss.org/wiki/MavenGettingStarted-Users">here</a> to configure Maven to use
the JBoss Maven repository.</p>
</dd>
<dt class="hdlist1">Clone the git repo</dt>
<dd>
<p><code>git clone https://github.com/undertow-io/undertow.git</code></p>
</dd>
<dt class="hdlist1">Build Undertow</dt>
<dd>
<p><code>cd undertow &amp;&amp; mvn install</code></p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The build should run all tests and complete without errors.</p>
</div>
<div class="admonitionblock warning">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
If you attempt to build with <code>-Dmaven.test.skip=true</code> for your initial build the build will fail, as the core test
jar will not be built and the Servlet module has a test scoped dependency on this jar. Either use <code>-DskipTests</code>, or
just let the tests run the first time.
</td>
</tr>
</tbody></table>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="undertow-core"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-core"></a>Undertow Core</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="bootstrapping-undertow"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#bootstrapping-undertow"></a>Bootstrapping Undertow</h3>
<div class="paragraph">
<p>There are two ways to bootstrap Undertow. The first and most simple is to use the <code>io.undertow.Undertow</code> builder API.
The second is to assemble a server using XNIO and the Undertow listener classes directly. This second approach requires
more code, but gives more flexibility. It is anticipated that for most use cases the builder API will be sufficient.</p>
</div>
<div class="paragraph">
<p>One thing that it is important to understand about Undertow is that there is not really any concept of an Undertow
container. Undertow applications are assembled from multiple handler classes, and it is up to the embedding application
to manage the lifecycle of all the these handlers. This was a deliberate design decision in order to give the embedding
application as much control as possible. This is generally only an issue if you have handlers that hold resources that
need to be cleaned up at server stop.</p>
</div>
<div class="sect3">
<h4 id="the-builder-api"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#the-builder-api"></a>The Builder API</h4>
<div class="paragraph">
<p>The builder API is accessed using the <code>io.undertow.Undertow</code> class. We will start by looking at a simple example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">HelloWorldServer</span> {

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="directive">final</span> <span class="predefined-type">String</span><span class="type">[]</span> args) {
        Undertow server = Undertow.builder()
                .addHttpListener(<span class="integer">8080</span>, <span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>)
                .setHandler(<span class="keyword">new</span> HttpHandler() {
                    <span class="annotation">@Override</span>
                    <span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
                        exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, <span class="string"><span class="delimiter">"</span><span class="content">text/plain</span><span class="delimiter">"</span></span>);
                        exchange.getResponseSender().send(<span class="string"><span class="delimiter">"</span><span class="content">Hello World</span><span class="delimiter">"</span></span>);
                    }
                }).build();
        server.start();
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example starts a simple server that returns <em>Hello World</em> to all requests. The server will listen on the
<code>localhost</code> address on port 8080 until the <code>server.stop()</code> method is called. When requests arrive they will be handled
by the first (and only) handler in the handler chain, which in this case simply sets a header and writes some content
(more information on handlers can be found in the <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/undertow-handler-guide.html">handlers guide</a>).</p>
</div>
<div class="paragraph">
<p>The builder will try and pick sensible defaults for all performance related parameters such as number of threads and
buffer sizes, however all these can be overridden directly using the builder. These options and their effects are
detailed in the <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/listeners.html">listeners guide</a>, and will not be repeated here.</p>
</div>
</div>
<div class="sect3">
<h4 id="assembling-a-server-manually"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#assembling-a-server-manually"></a>Assembling a Server Manually</h4>
<div class="paragraph">
<p>If you do not want to use the builder API then there are a few steps that you need to follow to create a server:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create an XNIO Worker. This worker manages both the IO and Worker threads for the server.</p>
</li>
<li>
<p>Create an XNIO SSL instance (optional, only required if HTTPS is in use)</p>
</li>
<li>
<p>Create an instance of the relevant Undertow listener class</p>
</li>
<li>
<p>Open a server socket using XNIO and set its accept listener</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The code for HTTP, HTTPS and AJP listeners is shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">Xnio xnio = Xnio.getInstance();

XnioWorker worker = xnio.createWorker(OptionMap.builder()
        .set(Options.WORKER_IO_THREADS, ioThreads)
        .set(Options.WORKER_TASK_CORE_THREADS, workerThreads)
        .set(Options.WORKER_TASK_MAX_THREADS, workerThreads)
        .set(Options.TCP_NODELAY, <span class="predefined-constant">true</span>)
        .getMap());

OptionMap socketOptions = OptionMap.builder()
        .set(Options.WORKER_IO_THREADS, ioThreads)
        .set(Options.TCP_NODELAY, <span class="predefined-constant">true</span>)
        .set(Options.REUSE_ADDRESSES, <span class="predefined-constant">true</span>)
        .getMap();

Pool&lt;<span class="predefined-type">ByteBuffer</span>&gt; buffers = <span class="keyword">new</span> ByteBufferSlicePool(BufferAllocator.DIRECT_BYTE_BUFFER_ALLOCATOR,bufferSize, bufferSize * buffersPerRegion);


<span class="keyword">if</span> (listener.type == ListenerType.AJP) {
    AjpOpenListener openListener = <span class="keyword">new</span> AjpOpenListener(buffers, serverOptions, bufferSize);
    openListener.setRootHandler(rootHandler);
    ChannelListener&lt;AcceptingChannel&lt;StreamConnection&gt;&gt; acceptListener = ChannelListeners.openListenerAdapter(openListener);
    AcceptingChannel&lt;? <span class="directive">extends</span> StreamConnection&gt; server = worker.createStreamConnectionServer(<span class="keyword">new</span> <span class="predefined-type">InetSocketAddress</span>(<span class="predefined-type">Inet4Address</span>.getByName(listener.host), listener.port), acceptListener, socketOptions);
    server.resumeAccepts();
} <span class="keyword">else</span> <span class="keyword">if</span> (listener.type == ListenerType.HTTP) {
    HttpOpenListener openListener = <span class="keyword">new</span> HttpOpenListener(buffers, OptionMap.builder().set(UndertowOptions.BUFFER_PIPELINED_DATA, <span class="predefined-constant">true</span>).addAll(serverOptions).getMap(), bufferSize);
    openListener.setRootHandler(rootHandler);
    ChannelListener&lt;AcceptingChannel&lt;StreamConnection&gt;&gt; acceptListener = ChannelListeners.openListenerAdapter(openListener);
    AcceptingChannel&lt;? <span class="directive">extends</span> StreamConnection&gt; server = worker.createStreamConnectionServer(<span class="keyword">new</span> <span class="predefined-type">InetSocketAddress</span>(<span class="predefined-type">Inet4Address</span>.getByName(listener.host), listener.port), acceptListener, socketOptions);
    server.resumeAccepts();
} <span class="keyword">else</span> <span class="keyword">if</span> (listener.type == ListenerType.HTTPS){
    HttpOpenListener openListener = <span class="keyword">new</span> HttpOpenListener(buffers, OptionMap.builder().set(UndertowOptions.BUFFER_PIPELINED_DATA, <span class="predefined-constant">true</span>).addAll(serverOptions).getMap(), bufferSize);
    openListener.setRootHandler(rootHandler);
    ChannelListener&lt;AcceptingChannel&lt;StreamConnection&gt;&gt; acceptListener = ChannelListeners.openListenerAdapter(openListener);
    XnioSsl xnioSsl;
    <span class="keyword">if</span>(listener.sslContext != <span class="predefined-constant">null</span>) {
        xnioSsl = <span class="keyword">new</span> JsseXnioSsl(xnio, OptionMap.create(Options.USE_DIRECT_BUFFERS, <span class="predefined-constant">true</span>), listener.sslContext);
    } <span class="keyword">else</span> {
        xnioSsl = xnio.getSslProvider(listener.keyManagers, listener.trustManagers, OptionMap.create(Options.USE_DIRECT_BUFFERS, <span class="predefined-constant">true</span>));
    }
    AcceptingChannel &lt;SslConnection&gt; sslServer = xnioSsl.createSslConnectionServer(worker, <span class="keyword">new</span> <span class="predefined-type">InetSocketAddress</span>(<span class="predefined-type">Inet4Address</span>.getByName(listener.host), listener.port), (ChannelListener) acceptListener, socketOptions);
    sslServer.resumeAccepts();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see it is quite a bit more code than just using the builder, however it does provide some flexibility that
the builder does not:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Complete control over all options</p>
</li>
<li>
<p>Ability to use different buffer pools and workers for each listener</p>
</li>
<li>
<p>XnioWorker instances can be shared between different server instances</p>
</li>
<li>
<p>Buffer pools can be shared between different server instances</p>
</li>
<li>
<p>Listeners can be given different root handlers</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In most cases this level of control is not necessary, and it is better to simply use the builder API.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="architecture-overview"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#architecture-overview"></a>Architecture Overview</h3>
<div class="paragraph">
<p>On thing that makes Undertow unique is that it has no concept of a global <em>container</em>. Instead an Undertow
server is assembled by the embedding application. This makes Undertow extremely flexible, and the embedding
application can basically just pick the parts that they need, and assemble them in whatever way makes sense.</p>
</div>
<div class="paragraph">
<p>An Undertow server is basically composed of three things, one (or more) XNIO worker instance, one or more connectors,
and a handler chain to handle incoming requests.</p>
</div>
<div class="sect3">
<h4 id="xnio"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#xnio"></a>XNIO</h4>
<div class="paragraph">
<p>Undertow is based on XNIO. The XNIO project provides a thin abstraction layer over Java NIO. In particular it provides
the following:</p>
</div>
</div>
<div class="sect3">
<h4 id="management-of-io-and-worker-threads"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#management-of-io-and-worker-threads"></a>Management of IO and Worker threads</h4>
<div class="paragraph">
<p>The XNIO worker manages both the IO threads, and a thread pool that can be used for blocking tasks. In general non-blocking
handlers will run from withing an IO thread, while blocking tasks such as Servlet invocations will be dispatched to the
worker thread pool.</p>
</div>
<div class="paragraph">
<p>IO threads run in a loop. This loop does three things:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Run any tasks that have been scheduled for execution by the IO thread</p>
</li>
<li>
<p>Run any scheduled tasks that that have hit their timeout</p>
</li>
<li>
<p>Call Selector.select(), and then invoke any callbacks for selected keys</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="channel-api"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#channel-api"></a>Channel API</h4>
<div class="paragraph">
<p>XNIO provides a channel abstraction, that abstracts away the underlying transport. Channels are notified of events
using the <code>ChannelListener</code> API, and do not have to deal with NIO interest OPs directly. At creation time channels are
assigned an IO Thread. This is the thread that will be used to execute all ChannelListener invocations for the channel.</p>
</div>
</div>
<div class="sect3">
<h4 id="listeners"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#listeners"></a>Listeners</h4>
<div class="paragraph">
<p>The concept of a listener in Undertow is basically the part of Undertow that handles incoming connections, and the
underlying wire protocol. By default Undertow ships with 5 different listeners:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>HTTP/1.1</p>
</li>
<li>
<p>HTTPS</p>
</li>
<li>
<p>AJP</p>
</li>
<li>
<p>SPDY (deprecated)</p>
</li>
<li>
<p>HTTP/2</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These listeners will generally do all IO in an IO thread using async IO. When a request has been fully parsed they will
create a <code>HttpServerExchange</code> object populated with the request data and then hand this to the handler chain.</p>
</div>
<div class="paragraph">
<p>Connectors are tied to an XNIO worker. If multiple connectors are setup to invoke the same handler chain they may share
a Worker, or they may have separate workers, depending on how they have been configured.</p>
</div>
<div class="paragraph">
<p>In general it should not matter to your application the type of connector that is in use, the exception being that not
all connectors support all features. For example AJP does not support HTTP upgrade.</p>
</div>
<div class="paragraph">
<p>For more information on listeners see the <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/listeners.html">listeners guide</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="handlers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#handlers"></a>Handlers</h4>
<div class="paragraph">
<p>The main Undertow functionality is provided by <code>io.undertow.server.HttpHandler</code> instances. These handlers can be chained
together to form a complete server.</p>
</div>
<div class="paragraph">
<p>The HttpHandler interface is quite simple:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">HttpHandler</span> {

    <span class="type">void</span> handleRequest(HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Handlers are generally chained together by explicitly specifying the next handler at construction time, there is no
<em>pipeline</em> concept, which means that a handler can pick the next handler to invoke based on the current request. A
typical handler might look something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SetHeaderHandler</span> <span class="directive">implements</span> HttpHandler {

    <span class="directive">private</span> <span class="directive">final</span> HttpString header;
    <span class="directive">private</span> <span class="directive">final</span> <span class="predefined-type">String</span> value;
    <span class="directive">private</span> <span class="directive">final</span> HttpHandler next;

    <span class="directive">public</span> SetHeaderHandler(<span class="directive">final</span> HttpHandler next, <span class="directive">final</span> <span class="predefined-type">String</span> header, <span class="directive">final</span> <span class="predefined-type">String</span> value) {
        <span class="local-variable">this</span>.next = next;
        <span class="local-variable">this</span>.value = value;
        <span class="local-variable">this</span>.header = <span class="keyword">new</span> HttpString(header);
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
        exchange.getResponseHeaders().put(header, value);
        next.handleRequest(exchange);
    }
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="listeners-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#listeners-2"></a>Listeners</h3>
<div class="paragraph">
<p>Listeners represent the entry point of an Undertow application. All incoming requests will come through a listener, and
a listener is responsible for translating a request into an instance of the <code>HttpServerExchange</code> object, and then
turning the result into a response that can be sent back to the client.</p>
</div>
<div class="paragraph">
<p>Undertow provides 4 built in listener types, HTTP/1.1, AJP, SPDY and HTTP/2. HTTPS is provided by using the HTTP listener
with an SSL enabled connection.</p>
</div>
<div class="paragraph">
<p>Note now that HTTP/2 is out it is expected that SPDY will be deprecated and eventually removed.</p>
</div>
<div class="sect3">
<h4 id="options"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#options"></a>Options</h4>
<div class="paragraph">
<p>Undertow listeners can be configured through the use of the <code>org.xnio.Option</code> class. In general options for XNIO that
control connection and worker level behaviour are listed in <code>org.xnio.Options</code>. Undertow specific options that control
connector level behaviour are listed in <code>io.undertow.UndertowOptions</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="xnio-workers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#xnio-workers"></a>XNIO workers</h4>
<div class="paragraph">
<p>All listeners are tied to an XNIO Worker instance. Usually there will only be a single worker instance that is shared
between listeners, however it is possible to create a new worker for each listener.</p>
</div>
<div class="paragraph">
<p>The worker instance manages the listeners IO threads, and also the default blocking task thread pool. There are several
main XNIO worker options that affect listener behaviour. These option can either be specified on the Undertow builder
as worker options, or at worker creating time if you are bootstrapping a server manually. These options all reside on
the <code>org.xnio.Options</code> class.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">WORKER_IO_THREADS</dt>
<dd>
<p>The number of IO threads to create. IO threads perform non blocking tasks, and should never perform blocking operations
because they are responsible for multiple connections, so while the operation is blocking other connections will
essentially hang. Two IO threads per CPU core is a reasonable default.</p>
</dd>
<dt class="hdlist1">WORKER_TASK_CORE_THREADS</dt>
<dd>
<p>The number of threads in the workers blocking task thread pool. When performing blocking operations such as Servlet
requests threads from this pool will be used. In general it is hard to give a reasonable default for this, as it depends
on the server workload. Generally this should be reasonably high, around 10 per CPU core.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="buffer-pool"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#buffer-pool"></a>Buffer Pool</h4>
<div class="paragraph">
<p>All listeners have a buffer pool, which is used to allocate pooled NIO <code>ByteBuffer</code> instances. These buffers are used
for IO operations, and the buffer size has a big impact on application performance. For servers the ideal size is
generally 16k, as this is usually the maximum amount of data that can be written out via a <code>write()</code> operation
(depending on the network setting of the operating system). Smaller systems may want to use smaller buffers to save
memory.</p>
</div>
<div class="paragraph">
<p>In some situations with blocking IO the buffer size will determine if a response is sent using chunked encoding or has a
fixed content length. If a response fits completely in the buffer and <code>flush()</code> is not called then a content length can
be set automatically.</p>
</div>
</div>
<div class="sect3">
<h4 id="common-listener-options"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#common-listener-options"></a>Common Listener Options</h4>
<div class="paragraph">
<p>In addition to the worker options the listeners take some other options that control server behaviour. These are all
part of the <code>io.undertow.UndertowOptions</code> class. Some of of these only make sense for specific protocols. You can set
options with the <code>Undertow.Builder.setServerOption</code>:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">MAX_HEADER_SIZE</dt>
<dd>
<p>The maximum size of a HTTP header block, in bytes. If a client sends more data that this as part of the request header
then the connection will be closed. Defaults to 50k.</p>
</dd>
<dt class="hdlist1">MAX_ENTITY_SIZE</dt>
<dd>
<p>The default maximum size of a request entity. If entity body is larger than this limit then a <code>java.io.IOException</code> will
be thrown at some point when reading the request (on the first read for fixed length requests, when too much data has
been read for chunked requests). This value is only the default size, it is possible for a handler to override this for
an individual request by calling <code>io.undertow.server.HttpServerExchange.setMaxEntitySize(long size)</code>. Defaults
to unlimited.</p>
</dd>
<dt class="hdlist1">MULTIPART_MAX_ENTITY_SIZE</dt>
<dd>
<p>The default max entity size when using the Multipart parser. This will generally be larger than <code>MAX_ENTITY_SIZE</code>. Having
a seperate setting for this allows for large files to be uploaded, while limiting the size of other requests.</p>
</dd>
<dt class="hdlist1">MAX_PARAMETERS</dt>
<dd>
<p>The maximum number of query parameters that are permitted in a request. If a client sends more than this number the
connection will be closed. This limit is necessary to protect against hash based denial of service attacks. Defaults to
1000.</p>
</dd>
<dt class="hdlist1">MAX_HEADERS</dt>
<dd>
<p>The maximum number of headers that are permitted in a request. If a client sends more than this number the
connection will be closed. This limit is necessary to protect against hash based denial of service attacks. Defaults to
200.</p>
</dd>
<dt class="hdlist1">MAX_COOKIES</dt>
<dd>
<p>The maximum number of cookies that are permitted in a request. If a client sends more than this number the
connection will be closed. This limit is necessary to protect against hash based denial of service attacks. Defaults to
200.</p>
</dd>
<dt class="hdlist1">URL_CHARSET</dt>
<dd>
<p>The charset to use to decode the URL and query parameters. Defaults to UTF-8.</p>
</dd>
<dt class="hdlist1">DECODE_URL</dt>
<dd>
<p>Determines if the listener will decode the URL and query parameters, or simply pass it through to the handler chain as
is. If this is set url encoded characters will be decoded to the charset specified in URL_CHARSET. Defaults to true.</p>
</dd>
<dt class="hdlist1">ALLOW_ENCODED_SLASH</dt>
<dd>
<p>If a request comes in with encoded / characters (i.e. %2F), will these be decoded.
This can cause security problems (link:http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-0450) if a front end
proxy does not perform the same decoding, and as a result this is disabled by default.</p>
</dd>
<dt class="hdlist1">ALLOW_EQUALS_IN_COOKIE_VALUE</dt>
<dd>
<p>If this is true then Undertow will allow non-escaped equals characters in unquoted cookie values. Unquoted cookie
values may not contain equals characters. If present the value ends before the equals sign. The remainder of the
cookie value will be dropped. Defaults to false.</p>
</dd>
<dt class="hdlist1">ALWAYS_SET_DATE</dt>
<dd>
<p>If the server should add a HTTP <code>Date</code> header to all response entities which do not already have one.
The server sets the header right before writing the response, if none was set by a handler before. Unlike
the <code>DateHandler</code> it will not overwrite the header. The current date string is cached, and is updated
every second. Defaults to true.</p>
</dd>
<dt class="hdlist1">ALWAYS_SET_KEEP_ALIVE</dt>
<dd>
<p>If a HTTP <code>Connection: keep-alive</code> header should always be set, even for HTTP/1.1 requests that are persistent by default. Even
though the spec does not require this header to always be sent it seems safer to always send it. If you are writing
some kind of super high performance application and are worried about the extra data being sent over the wire this
option allows you to turn it off. Defaults to true.</p>
</dd>
<dt class="hdlist1">MAX_BUFFERED_REQUEST_SIZE</dt>
<dd>
<p>The maximum size of a request that can be saved in bytes. Requests are buffered in a few situations, the main ones being SSL
renegotiation and saving post data when using FORM based auth. Defaults to 16,384 bytes.</p>
</dd>
<dt class="hdlist1">RECORD_REQUEST_START_TIME</dt>
<dd>
<p>If the server should record the start time of a HTTP request. This is necessary if you wish to log or otherwise use
the total request time, however has a slight performance impact, as it means that <code>System.nanoTime()</code> must be called for
each request. Defaults to false.</p>
</dd>
<dt class="hdlist1">IDLE_TIMEOUT</dt>
<dd>
<p>The amount of time a connection can be idle for before it is timed out. An idle connection is a connection that has had
no data transfer in the idle timeout period. Note that this is a fairly coarse grained approach, and small values will
cause problems for requests with a long processing time.</p>
</dd>
<dt class="hdlist1">REQUEST_PARSE_TIMEOUT</dt>
<dd>
<p>How long a request can spend in the parsing phase before it is timed out. This timer is started when the first bytes
of a request are read, and finishes once all the headers have been parsed.</p>
</dd>
<dt class="hdlist1">NO_REQUEST_TIMEOUT</dt>
<dd>
<p>The amount of time a connection can sit idle without processing a request, before it is closed by the server.</p>
</dd>
<dt class="hdlist1">ENABLE_CONNECTOR_STATISTICS</dt>
<dd>
<p>If this is true then the connector will record statistics such as requests processed and bytes sent/received. This has
a performance impact, although it should not be noticeable in most cases.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="alpn"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#alpn"></a>ALPN</h4>
<div class="paragraph">
<p><code>io.undertow.server.protocol.http.AlpnOpenListener</code></p>
</div>
<div class="paragraph">
<p>Note that the HTTP2 and SPDY connectors require the use of ALPN. Unfortunatly java does not provide a standard way of performing
ALPN at this time, so it is necessary to run java with a 3rd party ALPN library on the boot class path. For more information
see the <a href="http://eclipse.org/jetty/documentation/current/alpn-chapter.html">Jetty ALPN documentation</a>.</p>
</div>
<div class="paragraph">
<p>SPDY and HTTP2 should use the ALPN open listener to handle the ALPN protocol negotiation.</p>
</div>
</div>
<div class="sect3">
<h4 id="http-listener"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#http-listener"></a>HTTP Listener</h4>
<div class="paragraph">
<p><code>io.undertow.server.protocol.http.HttpOpenListener</code></p>
</div>
<div class="paragraph">
<p>The HTTP listener is the most commonly used listener type, and deals with HTTP/1.0 and HTTP/1.1. It only takes one additional option.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">ENABLE_HTTP2</dt>
<dd>
<p>If this is true then the connection can be processed as a HTTP/2 <em>prior knowledge</em> connection. If a HTTP/2 client connects directly
to the listener with a HTTP/2 connection preface then the HTTP/2 protocol will be used instead of HTTP/1.1.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="ajp-listener"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#ajp-listener"></a>AJP Listener</h4>
<div class="paragraph">
<p><code>io.undertow.server.protocol.ajp.AjpOpenListener</code></p>
</div>
<div class="paragraph">
<p>The AJP listener allows the use of the AJP protocol, as used by the apache modules mod_jk and mod_proxy_ajp. It is a binary
protocol that is slightly more efficient protocol than HTTP, as some common strings are replaced by integers. If the front
end load balancer supports it then it is recommended to use HTTP2 instead, as it is both a standard protocol and more efficient.</p>
</div>
<div class="paragraph">
<p>This listener has one specific option:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">MAX_AJP_PACKET_SIZE</dt>
<dd>
<p>Controls the maximum size of an AJP packet. This setting must match on both the load balancer and backend server.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="http2-listener"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#http2-listener"></a>HTTP2 Listener</h4>
<div class="paragraph">
<p>HTTP/2 support is implemented on top of HTTP/1.1 (it is not possible to have a HTTP/2 server that does not also support
HTTP/1). There are three different ways a HTTP/2 connection can be established:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">ALPN</dt>
<dd>
<p>This is the most common way (and the only way many browsers currently support). It requires HTTPS, and uses the application
layer protocol negotiation SSL extension to negotiate that connection will use HTTP/2.</p>
</dd>
<dt class="hdlist1">Prior Knowledge</dt>
<dd>
<p>This involves the client simply sending a HTTP/2 connection preface and assuming the server will support it. This is not
generally used on the open internet, but it useful for things like load balancers when you know the backend server will
support HTTP/2.</p>
</dd>
<dt class="hdlist1">HTTP Upgrade</dt>
<dd>
<p>This involves the client sending an <code>Upgrade: h2c</code> header in the initial request. If this upgrade is accepted then the server
will initiate a HTTP/2 connection, and send back the response to the initial request using HTTP/2.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Depending on the way HTTP/2 is being used the setup for the listeners is slightly different.</p>
</div>
<div class="paragraph">
<p>If you are using the Undertow builder all that is required is to call <code>setServerOption(ENABLE_HTTP2, true)</code>, and HTTP/2
support will be automatically added for all HTTP and HTTPS listeners.</p>
</div>
<div class="admonitionblock warning">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
JDK8 does not currently support ALPN. To use HTTP/2 over HTTPS it is necessary to use the Jetty ALPN extension on the
boot class path. Instructions for Jetty ALPN can be found at <a href="http://www.eclipse.org/jetty/documentation/9.2.8.v20150217/alpn-chapter.html" class="bare">http://www.eclipse.org/jetty/documentation/9.2.8.v20150217/alpn-chapter.html</a>
</td>
</tr>
</tbody></table>
</div>
<div class="paragraph">
<p>The following options are supported:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">HTTP2_SETTINGS_HEADER_TABLE_SIZE</dt>
<dd>
<p>The size of the header table that is used for compression. Increasing this will use more memory per connection, but potentially
decrease the amount of data that is sent over the wire. Defaults to 4096.</p>
</dd>
<dt class="hdlist1">HTTP2_SETTINGS_ENABLE_PUSH</dt>
<dd>
<p>If server push is enabled for this connection.</p>
</dd>
<dt class="hdlist1">HTTP2_SETTINGS_MAX_CONCURRENT_STREAMS</dt>
<dd>
<p>The maximum number of streams a client is allowed to have open at any one time.</p>
</dd>
<dt class="hdlist1">HTTP2_SETTINGS_INITIAL_WINDOW_SIZE</dt>
<dd>
<p>The initial flow control window size.</p>
</dd>
<dt class="hdlist1">HTTP2_SETTINGS_MAX_FRAME_SIZE</dt>
<dd>
<p>The maximum frame size.</p>
</dd>
<dt class="hdlist1">HTTP2_SETTINGS_MAX_HEADER_LIST_SIZE</dt>
<dd>
<p>The maximum size of the headers that this server is prepared to accept.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="spdy-listener"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#spdy-listener"></a>SPDY Listener</h4>
<div class="paragraph">
<p><code>io.undertow.server.protocol.spdy.SpdyOpenListener</code></p>
</div>
<div class="paragraph">
<p>The SPDY protocol is an experimental protocol designed by Google, that formed the basis of HTTP2. Now that HTTP2 has been
adopted by browser vendors it should be used instead.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="built-in-handlers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#built-in-handlers"></a>Built in Handlers</h3>
<div class="paragraph">
<p>Undertow contains a number of build in handlers that provide common functionality. Most of these handlers can be created
using static methods on the <code>io.undertow.Handlers</code> utility class.</p>
</div>
<div class="paragraph">
<p>The most common of these handlers are detailed below.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Path</dt>
<dd>
<p>The path matching handler allows you to delegate to a handler based on the path of the request. It can match on either
an exact path or a path prefix, and will update the exchanges relative path based on the selected path. Paths are first
checked against an exact match, and then via longest prefix match.</p>
</dd>
<dt class="hdlist1">Virtual Host</dt>
<dd>
<p>This handler delegates to a handler based on the contents of the <code>Host:</code> header, which allows you to select a different
chain to handle different hosts.</p>
</dd>
<dt class="hdlist1">Path Template</dt>
<dd>
<p>Similar to the path handler, however the path template handler allows you to use URI template expressions in the path,
for example /rest/{name}. The value of the relevant path template items are stored as an attachment on the exchange,
under the <code>io.undertow.server.handlers.PathTemplateHandler#PATH_TEMPLATE_MATCH</code> attachment key.</p>
</dd>
<dt class="hdlist1">Resource</dt>
<dd>
<p>The resource handler is used to serve static resources such as files. This handler takes a <code>ResourceManager</code> instance,
that is basically a file system abstraction. Undertow provides file system and class path based resource mangers, as
well as a caching resource manager that wraps an existing resource manager to provide in memory caching support.</p>
</dd>
<dt class="hdlist1">Predicate</dt>
<dd>
<p>The predicate handler picks between two possible handlers based on the value of a predicate that is resolved against the
exchange. For more information see the <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/predicates-attributes-handlers.html">predicates guide</a>.</p>
</dd>
<dt class="hdlist1">HTTP Continue</dt>
<dd>
<p>There are multiple handlers that deal with requests that expect a HTTP 100 Continue response. The HTTP Continue Read
Handler will automatically send a continue response for requests that require it the first time a handler attempts to
read the request body.
The HTTP Continue Accepting handler will immediately either send a 100 or a 417 response depending on the value of a
predicate. If no predicate is supplied it all immediately accept all requests. If a 417 response code is send the
next handler is not invoked and the request will be changed to be non persistent.</p>
</dd>
<dt class="hdlist1">Websocket</dt>
<dd>
<p>Handler that handles incoming web socket connections. See the <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/websockets.html">websockets guide</a> for details.</p>
</dd>
<dt class="hdlist1">Redirect</dt>
<dd>
<p>A handler that redirects to a specified location.</p>
</dd>
<dt class="hdlist1">Trace</dt>
<dd>
<p>A handler that handles HTTP TRACE requests, as specified by the HTTP RFC.</p>
</dd>
<dt class="hdlist1">Header</dt>
<dd>
<p>A handler that sets a response header.</p>
</dd>
<dt class="hdlist1">IP Access Control</dt>
<dd>
<p>A handler that allows or disallows a request based on the IP address of the remote peer.</p>
</dd>
<dt class="hdlist1">ACL</dt>
<dd>
<p>A handler that allows or disallows a request based on an access control list. Any attribute of the exchange can be used
as the basis of this comparison.</p>
</dd>
<dt class="hdlist1">URL Decoding</dt>
<dd>
<p>A handler that decodes the URL and query parameters into a specified charset. It may be that different resources may
require a different charset for the URL. In this case it is possible to set the Undertow listener to not decode the URL,
and instead multiple instances of this handler at an appropriate point in the handler chain. For example this could
allow you to have different virtual hosts use different URL encodings.</p>
</dd>
<dt class="hdlist1">Set Attribute</dt>
<dd>
<p>Sets an arbitrary attribute on the exchange. Both the attribute and the value are specified as exchange attributes, so
this handler can essentially be used to modify any part of the exchange. For more information see the section on
<a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/predicates-attributes-handlers.html">exchange attributes</a>.</p>
</dd>
<dt class="hdlist1">Rewrite</dt>
<dd>
<p>Handler that provides URL rewrite support.</p>
</dd>
<dt class="hdlist1">Graceful Shutdown</dt>
<dd>
<p>Returns a handler that can be used to make sure all running requests are finished before the server shuts down. This
handler tracks running requests, and will reject new ones once shutdown has started.</p>
</dd>
<dt class="hdlist1">Proxy Peer Address</dt>
<dd>
<p>This handler can be used by servers that are behind a reverse proxy. It will modify the exchanges peer address and
protocol to match that of the X-Forwarded-* headers that are sent by the reverse proxy. This means downstream handlers
will see that actual clients peer address, rather than that of the proxy.</p>
</dd>
<dt class="hdlist1">Request Limiting Handler</dt>
<dd>
<p>Handler that limits the number of concurrent requests. If the number exceeds the limit requests are queued. If the
queue fills up then requests are rejected.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="undertow-handler-authors-guide"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-handler-authors-guide"></a>Undertow Handler Authors Guide</h3>
<div class="paragraph">
<p>This guide provides an overview of how to write native handlers for Undertow. It does not cover every API method
on the <code>HttpServerExchange</code> object, as many of them are self explanatory or covered by the javadoc. Instead
this guide focuses on the concepts you will need to write an Undertow handler.</p>
</div>
<div class="paragraph">
<p>Lets start with a simple example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">HelloWorldServer</span> {

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="directive">final</span> <span class="predefined-type">String</span><span class="type">[]</span> args) {
        Undertow server = Undertow.builder()                                                    <span class="comment">//Undertow builder</span>
                .addListener(<span class="integer">8080</span>, <span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>)                                                 <span class="comment">//Listener binding</span>
                .setHandler(<span class="keyword">new</span> HttpHandler() {                                                 <span class="comment">//Default Handler</span>
                    <span class="annotation">@Override</span>
                    <span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
                        exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, <span class="string"><span class="delimiter">"</span><span class="content">text/plain</span><span class="delimiter">"</span></span>);  <span class="comment">//Response Headers</span>
                        exchange.getResponseSender().send(<span class="string"><span class="delimiter">"</span><span class="content">Hello World</span><span class="delimiter">"</span></span>);                       <span class="comment">//Response Sender</span>
                    }
                }).build();
        server.start();
    }

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For the most part this is all fairly self explanatory:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">The Undertow Builder</dt>
<dd>
<p>This API enables you to quickly configure and launch an Undertow server. It is intended for use is embedded and testing
environments. At this stage the API is still subject to change.</p>
</dd>
<dt class="hdlist1">Listener Binding</dt>
<dd>
<p>The next line tells the Undertow server to bind to localhost on port 8080.</p>
</dd>
<dt class="hdlist1">Default Handler</dt>
<dd>
<p>This is the handler that will be matched if a URL does not match any of the paths that are registered with Undertow. In
this case we do not have any other handlers registered, so this handler is always invoked.</p>
</dd>
<dt class="hdlist1">Response Headers</dt>
<dd>
<p>This sets the content type header, which is fairly self explanatory. One thing to note is that Undertow does not use
<code>String</code> as the key for the header map, but rather a case insensitive string <code>io.undertow.util.HttpString</code>. The
<code>io.undertow.utils.Headers</code> class contains predefined constants for all common headers.</p>
</dd>
<dt class="hdlist1">Response Sender</dt>
<dd>
<p>The Undertow sender API is just one way of sending a response. The sender will be covered in more detail later, but in
this case as no completion callback has been specified the sender knows that the provided string is the complete response,
and as such will set a content length header for us and close the response when done.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>From now on our code examples will focus on the handlers themselves, and not on the code to setup a server.</p>
</div>
<div class="sect3">
<h4 id="request-lifecycle"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#request-lifecycle"></a>Request Lifecycle</h4>
<div class="paragraph">
<p>(This is also covered in the <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/undertow-request-lifecycle.html">Request Lifecycle</a> document.)</p>
</div>
<div class="paragraph">
<p>When a client connects to the server Undertow creates a <code>io.undertow.server.HttpServerConnection</code>. When the client sends
a request it is parsed by the Undertow parser, and then the resulting <code>io.undertow.server.HttpServerExchange</code> is passed
to the root handler. When the root handler finishes one of 4 things can happen:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">The exchange can be already completed</dt>
<dd>
<p>And exchange is considered complete if both request and response channels have been fully read/written. For requests
with no content (such as GET and HEAD) the request side is automatically considered fully read. The read side is considered
complete when a handler has written out the full response and closed and fully flushed the response channel. If an exchange
is already complete then no action is taken, as the exchange is finished.</p>
</dd>
<dt class="hdlist1">The root handler returns normally without completing the exchange</dt>
<dd>
<p>In this case the exchange will be completed by calling <code>HttpServerExchange.endExchange()</code>. The semantics of <code>endExchange()</code>
are discussed later.</p>
</dd>
<dt class="hdlist1">The root handler returns with an Exception</dt>
<dd>
<p>In this case a response code of <code>500</code> will be set, and the exchange will be ended using <code>HttpServerExchange.endExchange()</code>.</p>
</dd>
<dt class="hdlist1">The root handler can return after <code>HttpServerExchange.dispatch()</code> has been called, or after async IO has been started</dt>
<dd>
<p>In this case the dispatched task will be submitted to the dispatch executor, or if async IO has been started on either
the request or response channels then this will be started. In this case the exchange will not be finished, it is up
to your async task to finish the exchange when it is done processing.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>By far the most common use of <code>HttpServerExchange.dispatch()</code> is to move execution from an IO thread where blocking is not
allowed into a worker thread, which does allow for blocking operations. This pattern generally looks like:</p>
</div>
<div id="dispatch-code" class="listingblock">
<div class="title">Dispatching to a worker thread</div>
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
    <span class="keyword">if</span> (exchange.isInIoThread()) {
      exchange.dispatch(<span class="local-variable">this</span>);
      <span class="keyword">return</span>;
    }
    <span class="comment">//handler code</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Because exchange is not actually dispatched until the call stack returns you can be sure that more that one thread is
never active in an exchange at once. The exchange is not thread safe, however it can be passed between multiple threads
as long as both threads do not attempt to modify it at once, and there is a happens before action (such as a thread pool
dispatch) in between the first and second thread access.</p>
</div>
</div>
<div class="sect3">
<h4 id="ending-the-exchange"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#ending-the-exchange"></a>Ending the exchange</h4>
<div class="paragraph">
<p>As mentioned above, and exchange is considered done once both the request and response channels have been closed and flushed.</p>
</div>
<div class="paragraph">
<p>There are two ways to end an exchange, either by fully reading the request channel, and calling <code>shutdownWrites()</code> on the
response channel and then flushing it, or by calling <code>HttpServerExchange.endExchange()</code>. When <code>endExchange()</code> is called
Undertow will check if and content has been generated yet, if it has then it will simply drain the request channel, and
close and flush the response channel. If not and there are any default response listeners registered on the exchange
then Undertow will give each of them a chance to generate a default response. This mechanism is how default error pages
are generated.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-undertow-buffer-pool"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#the-undertow-buffer-pool"></a>The Undertow Buffer Pool</h4>
<div class="paragraph">
<p>As Undertow is based on NIO it uses <code>java.nio.ByteBuffer</code> whenever buffering is needed. These buffers are pooled, and
should not be allocated on demand as this will severely impact performance. The buffer pool can be obtained by calling
<code>HttpServerConnection.getBufferPool()</code>.</p>
</div>
<div class="paragraph">
<p>Pooled buffers <strong>must</strong> be freed after use, as they will not be cleaned up by the garbage collector. The size of the
buffers in the pool is configured when the server is created. Empirical testing has shown that if direct buffers
are being used 16kb buffers are optimal if maximum performance is required (as this corresponds to the default socket
buffer size on Linux).</p>
</div>
</div>
<div class="sect3">
<h4 id="non-blocking-io"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#non-blocking-io"></a>Non-blocking IO</h4>
<div class="paragraph">
<p>By default Undertow uses non-blocking XNIO channels, and requests initially start off in an XNIO IO thread. These channels
can be used directly to send a receive data. These channels are quite low level however, so to that end Undertow provides
some abstractions to make using them a little bit easier.</p>
</div>
<div class="paragraph">
<p>The easiest way to send a response using non-blocking IO is to use the sender API as shown above. It contains several
versions of the <code>send()</code> method for both <code>byte</code> and <code>String</code> data. Some versions of the method take a callback that is
invoked when the send is complete, other versions do not take a callback and instead end the exchange when the send is
complete.</p>
</div>
<div class="paragraph">
<p>Note that the sender API does not support queueing, you may not call <code>send()</code> again until after the callback has been
notified.</p>
</div>
<div class="paragraph">
<p>When using versions of the <code>send()</code> method that do not take a callback the <code>Content-Length</code> header will be automatically
set, otherwise you must set this yourself to avoid using chunked encoding.</p>
</div>
<div class="paragraph">
<p>The sender API also supports blocking IO, if the exchange has been put into blocking mode by invoking
<code>HttpServerExchange.startBlocking()</code> then the Sender will send its data using the exchanges output stream.</p>
</div>
</div>
<div class="sect3">
<h4 id="blocking-io"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#blocking-io"></a>Blocking IO</h4>
<div class="paragraph">
<p>Undertow provides full support for blocking IO. It is not advisable to use blocking IO in an XNIO worker thread, so you
will need to make sure that the request has been dispatched to a worker thread pool before attempting to read or write.</p>
</div>
<div class="paragraph">
<p>The code to dispatch to a worker thread can be found <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#dispatch-code">above</a>.</p>
</div>
<div class="paragraph">
<p>To begin blocking IO call <code>HttpServerExchange.startBlocking()</code>. There are two versions of this method, the one which
does not take any parameters which will use Undertow’s default stream implementations, and
<code>HttpServerExchange.startBlocking(BlockingHttpServerExchange blockingExchange)</code> which allows you to customise the
streams that are in use. For example the servlet implementation uses the second method to replace Undertow’s default
streams with Servlet(Input/Output)Stream implementations.</p>
</div>
<div class="paragraph">
<p>Once the exchange has been but into blocking mode you can now call <code>HttpServerExchange.getInputStream()</code> and
<code>HttpServerExchange.getOutputStream()</code>, and write data to them as normal. You can also still use the sender API
described above, however in this case the sender implementation will use blocking IO.</p>
</div>
<div class="paragraph">
<p>By default Undertow uses buffering streams, using buffers taken from the buffer pool. If a response is small enough
to fit in the buffer then a <code>Content-Length</code> header will automatically be set.</p>
</div>
</div>
<div class="sect3">
<h4 id="headers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#headers"></a>Headers</h4>
<div class="paragraph">
<p>Request and response headers are accessible through the <code>HttpServerExchange.getRequestHeaders()</code> and
<code>HttpServerExchange.getResponseHeaders()</code> methods. These methods return a <code>HeaderMap</code>, an optimised map implementation.</p>
</div>
<div class="paragraph">
<p>Headers are written out with the HTTP response header when the first data is written to the underlying channel (this
may not be the same time as the first time data is written if buffering is used).</p>
</div>
<div class="paragraph">
<p>If you wish to force the headers to be written you can call the <code>flush()</code> method on either the response channel or stream.</p>
</div>
</div>
<div class="sect3">
<h4 id="http-upgrade"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#http-upgrade"></a>HTTP Upgrade</h4>
<div class="paragraph">
<p>In order to perform a HTTP upgrade you can call
<code>HttpServerExchange.upgradeChannel(ExchangeCompletionListener upgradeCompleteListener)</code>, the response code will be set
to 101, and once the exchange is complete your listener will be notified. Your handler is responsible for setting
any appropriate headers that the upgrade client will be expecting.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="undertow-request-lifecyle"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-request-lifecyle"></a>Undertow Request Lifecyle</h3>
<div class="paragraph">
<p>This document covers the lifecycle of a web request from the point of view of the Undertow server.</p>
</div>
<div class="paragraph">
<p>When a connection is established XNIO invokes the <code>io.undertow.server.HttpOpenListener</code>, this listener
creates a new <code>io.undertow.server.HttpServerConnection</code> to hold state associated with this connection,
and then invokes <code>io.undertow.server.HttpReadListener</code>.</p>
</div>
<div class="paragraph">
<p>The HTTP read listener is responsible for parsing the incoming request, and creating a new
<code>io.undertow.server.HttpServerExchange</code> to store the request state. The exchange object contains both the request
and response state.</p>
</div>
<div class="paragraph">
<p>At this point the request and response channel wrappers are setup, that are responsible for decoding and encoding
the request and response data.</p>
</div>
<div class="paragraph">
<p>The root handler is then executed via <code>io.undertow.server.HttpHandlers#executeRootHandler</code>. Handlers are chained
together, and each handler can modify the exchange, send a response, or delegate to a different handler. At this point
there are a few different things that can happen:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The exchange can be finished. This happens when both the request and response channels are closed. If a content
length is set then the channel will automatically close once all the data has been written. This can also be forced
by calling <code>HttpServerExchange.endExchange()</code>, and if no data has been written yet any default response listeners
that have been registered with the exchange will be given the opportunity to generate a default response, such as
an error page. Once the current exchange is finished the exchange completion listeners will be run. The last completion
listener will generally start processing the next request on the connection, and will have been setup by the read listener.</p>
</li>
<li>
<p>The exchange can be dispatched by calling one of the <code>HttpServerExchange.dispatch</code> methods. This is similar to
the servlet <code>startAsync()</code> method. Once the call stack returns then the dispatch task (if any) will be run in
the provided executor (if no executor is provided it will be ran by the XNIO worker). The most common use of a
dispatch is to move from executing in an IO thread (where blocking operations are not allowed), to a worker thread
that can block. This pattern looks like:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
    <span class="keyword">if</span> (exchange.isInIoThread()) {
      exchange.dispatch(<span class="local-variable">this</span>);
      <span class="keyword">return</span>;
    }
    <span class="comment">//handler code</span>
}</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Reads/Writes can be resumed on a request or response channel. Internally this is treated like a dispatch,
and once the call stack returns the relevant channel will be notified about IO events. The reason why the operation
does not take effect until the call stack returns is to make sure that we never have multiple threads acting in the
same exchange.</p>
</li>
<li>
<p>The call stack can return without the exchange being dispatched. If this happens <code>HttpServerExchange.endExchange()</code>
will be called, and the request will be finished.</p>
</li>
<li>
<p>An exception can be thrown. If this propagates all the way up the call stack the exchange will be ended with a 500
response code.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="error-handling"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#error-handling"></a>Error Handling</h3>
<div class="paragraph">
<p>Error handling is accomplished by through the use of default response listeners. These are listeners that can generate
a response if the exchange is ended without a response being sent.</p>
</div>
<div class="admonitionblock note">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This is completely different to Servlet error handling. Servlet error handling is implemented as part of Undertow
Servlet, and follows the standard Servlet rules.
</td>
</tr>
</tbody></table>
</div>
<div class="paragraph">
<p>In general there are two types of errors that we need to worry about, handlers that throw exceptions or handlers that
set an error response code and then call <code>HttpServerExchange.endExchange()</code>.</p>
</div>
<div class="sect3">
<h4 id="exceptions"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#exceptions"></a>Exceptions</h4>
<div class="paragraph">
<p>The easiest way to handle exceptions is to catch them in an outer handler. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ErrorHandler</span> <span class="directive">implements</span> HttpHandler {

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="keyword">try</span> {
            next.handleRequest(exchange);
        } <span class="keyword">catch</span> (<span class="exception">Exception</span> e) {
            <span class="keyword">if</span>(exchange.isResponseChannelAvailable()) {
                <span class="comment">//handle error</span>
            }
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The allows you application to handle exceptions in whatever manner you see fit.</p>
</div>
<div class="paragraph">
<p>If the exception propagates out of the handler chain a 500 response code will be set and the exchange can be ended.</p>
</div>
</div>
<div class="sect3">
<h4 id="default-response-listeners"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#default-response-listeners"></a>Default Response Listeners</h4>
<div class="paragraph">
<p>Default response listener allow you to generate a default page if the exchange is ended without a response body. These
handlers should test for an error response code, and then generate an appropriate error page.</p>
</div>
<div class="paragraph">
<p>Note that these handlers will be run for all requests that terminate with no content, but generating default content for
successful requests will likely cause problems.</p>
</div>
<div class="paragraph">
<p>Default response listeners can be registered via the
<code>HttpServerExchange#addDefaultResponseListener(DefaultResponseListener)</code> method. They will be called in the reverse order
that they are registered, so the last handler registered is the first to be called.</p>
</div>
<div class="paragraph">
<p>The following example shows a handler that will generate a simple next based error page for 500 errors:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SimpleErrorPageHandler</span> <span class="directive">implements</span> HttpHandler {

    <span class="directive">private</span> <span class="directive">final</span> HttpHandler next;

    <span class="directive">public</span> SimpleErrorPageHandler(<span class="directive">final</span> HttpHandler next) {
        <span class="local-variable">this</span>.next = next;
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
        exchange.addDefaultResponseListener(<span class="keyword">new</span> DefaultResponseListener() {
            <span class="annotation">@Override</span>
            <span class="directive">public</span> <span class="type">boolean</span> handleDefaultResponse(<span class="directive">final</span> HttpServerExchange exchange) {
                <span class="keyword">if</span> (!exchange.isResponseChannelAvailable()) {
                    <span class="keyword">return</span> <span class="predefined-constant">false</span>;
                }
                <span class="predefined-type">Set</span>&lt;<span class="predefined-type">Integer</span>&gt; codes = responseCodes;
                <span class="keyword">if</span> (exchange.getResponseCode() == <span class="integer">500</span>) {
                    <span class="directive">final</span> <span class="predefined-type">String</span> errorPage = <span class="string"><span class="delimiter">"</span><span class="content">&lt;html&gt;&lt;head&gt;&lt;title&gt;Error&lt;/title&gt;&lt;/head&gt;&lt;body&gt;Internal Error&lt;/body&gt;&lt;/html&gt;</span><span class="delimiter">"</span></span>;
                    exchange.getResponseHeaders().put(Headers.CONTENT_LENGTH, <span class="string"><span class="delimiter">"</span><span class="delimiter">"</span></span> + errorPage.length());
                    exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, <span class="string"><span class="delimiter">"</span><span class="content">text/html</span><span class="delimiter">"</span></span>);
                    Sender sender = exchange.getResponseSender();
                    sender.send(errorPage);
                    <span class="keyword">return</span> <span class="predefined-constant">true</span>;
                }
                <span class="keyword">return</span> <span class="predefined-constant">false</span>;
            }
        });
        next.handleRequest(exchange);
    }
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="security"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#security"></a>Security</h3>
<div class="paragraph">
<p>Undertow has a flexible security architecture that provides several built in authentication mechanisms,
as well as providing an API to allow you to provide custom mechanisms. Mechanisms can be combined (as
much as the relevant specifications allow). This document covers the details of the core Undertow
security API. For details on how these are used in servlet deployments see <a href="http://undertow.io/undertow-docs/servlet/security.html">Servlet Security</a>.</p>
</div>
<div class="sect3">
<h4 id="the-securitycontext"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#the-securitycontext"></a>The SecurityContext</h4>
<div class="paragraph">
<p>The core of Undertow’s security architecture is the SecurityContext. It is accessible via the
<code>HttpServerExchange.getSecurityContext()</code> method. The security context is responsible for maintaining
all security related state for the request, including configured authentication mechanisms and the
current authenticated user.</p>
</div>
</div>
<div class="sect3">
<h4 id="security-handlers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#security-handlers"></a>Security Handlers</h4>
<div class="paragraph">
<p>Security within Undertow is implemented as a set of asynchronous handlers and a set of authentication
mechanisms co-ordinated by these handlers.</p>
</div>
<div class="paragraph">
<p>Early in the call chain is a handler called <code>SecurityInitialHandler</code>, this is where the security processing
beings, this handler ensures that an empty <code>SecurityContext</code> is set on the current <code>HttpServerExchange</code></p>
</div>
<div class="ulist">
<ul>
<li>
<p>Allow authentication to occur in the call as early as possible.</p>
</li>
<li>
<p>Allows for use of the mechanisms in numerous scenarios and not just for servlets.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The <code>SecurityContext</code> is responsible for both holding the state related to the currently authenticated user
and also for holding the configured mechanisms for authentication (<code>AuthenticationMechanism</code>) and providing
methods to work with both of these. As this <code>SecurityContext</code> is replacable a general configuration
can be applied to a complete server with custom configuration replacing it later in the call.</p>
</div>
<div class="paragraph">
<p>After the <code>SecurityContext</code> has been established subseqeunt handlers can then add authentication mechanisms
to the context, to simplify this Undertow contains a handler called <code>AuthenticationMechanismsHandler</code>
this handler can be created with a set of <code>AuthenticationMechanism</code> mechanisms and will set them all on the
established <code>SecurityContext</code>.  Alternatively custom handlers could be used to add mechanisms one at a time
bases on alternative requirements.</p>
</div>
<div class="paragraph">
<p>The next handler in the authentication process is the <code>AuthenticationConstraintHandler</code>, this handler is
responsible for checking the current request and identifying if authentication should be marked as being
required for the current request. This handler can take a <a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/predicates-attributes-handlers.html">Predicate</a>
that makes a decision about if the request requires authentication.</p>
</div>
<div class="paragraph">
<p>The final handler in this chain is the <code>AuthenticationCallHandler</code>, this handler is responsible for
ensuring the <code>SecurityContext</code> is called to actually perform the authentication process, depending
on any identified constraint this will either mandate authentication or only perform authentication
if appropriate for the configured mechanisms.</p>
</div>
<div class="paragraph">
<p>There is no requirement for these handlers to be executed consecutively, the only requirement is that first
the <code>SecurityContext</code> is established, then the authentications and constrain check can be
performed in any order and finally the <code>AuthenticationCallHandler</code> must be used before any processing of
a potentially protected resource is called.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./Undertow_files/security_handlers.png" alt="An Example Security Chain">
</div>
<div class="title">Figure 1. An Example Security Chain</div>
</div>
<div class="paragraph">
<p>Security mechanisms that are to be used must implement the following interface: -</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">AuthenticationMechanism</span> {

    AuthenticationMechanismOutcome authenticate(<span class="directive">final</span> HttpServerExchange exchange, <span class="directive">final</span> SecurityContext securityContext);

    ChallengeResult sendChallenge(<span class="directive">final</span> HttpServerExchange exchange, <span class="directive">final</span> SecurityContext securityContext);
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>AuthenticationMechanismOutcome</code> is used by the mechanism to indicate the status of the attempted authentication.</p>
</div>
<div class="paragraph">
<p>The three options are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>AUTHENTICATED</strong> - The authentication was successful. No further methods will be tried and no challenge will be sent.</p>
</li>
<li>
<p><strong>NOT_ATTEMPTED</strong> - There was not enough information available to attempt an authentication. The next mechanism will be
tried. If this was the last mechanism and authentication is required then a challenge will be sent by calling the
<code>sendChallenge</code> method on all the mechanisms in order. If authentication is not required then the request will
proceed with no authenticated principal.</p>
</li>
<li>
<p><strong>NOT_AUTHENTICATED</strong> - The authentication failed, usually this is due to invalid credentials. The authentication process
will not proceed further, and a new challenge will be sent to the client.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Regardless of if authentication has been flagged as being required when the request reaches the <code>AuthenticationCallHandler</code> the
<code>SecurityContext</code> is called to commence the process.  The reason this happens regardless of if authentication is flagged as
required is for a few reasons:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The client may have sent additional authentication tokens and have expectations the response will take these into account.</p>
</li>
<li>
<p>We may be able to verify the remote user without any additional rount trips, especially where authentication has already occurred.</p>
</li>
<li>
<p>The authentication mechanism may need to pass intermediate updates to the client so we need to ensure any inbound tokens are valid.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When authentication runs the <code>authenticate</code> method on each configured <code>AuthenticationMechanism</code> is called in turn, this continues
until one of the following occurs:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A mechanism successfully authenticates the request and returns <code>AUTHENTICATED</code>.</p>
</li>
<li>
<p>A mechanism attempts but does not complete authentication and returns <code>NOT_AUTHENTICATED</code>.</p>
</li>
<li>
<p>The list of mechanisms is exhausted.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>At this point if the response was <code>AUTHENTICATED</code> then the request will be allowed through and passed onto the next handler.</p>
</div>
<div class="paragraph">
<p>If the request is <code>NOT_AUTHENTICATED</code> then either authentication failed or a mechanism requires an additional round trip with the
client, either way the <code>sendChallenge</code> method of each defined <code>AuthenticationMethod</code> is called in turn and the response sent back
to the client.  All mechanisms are called as even if one mechanism is mid-authentication the client can still decide to abandon
that mechanism and switch to an alternative mechanism so all challenges need to be re-sent.</p>
</div>
<div class="paragraph">
<p>If the list of mechanisms was exhausted then the previously set authentication constraint needs to be checked, if authentication was
not required then the request can proceed to the next handler in the chain and that will be then of authentication for this request
(unless a later handler mandates authentication and requests authentication is re-atempted).  If however authentication was required
then as with a <code>NOT_AUTHENTICATED</code> response each mechanism has <code>sendChallenge</code> called in turn to generate an authentication challenge
to send to the client.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="predicates-attributes-and-handlers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#predicates-attributes-and-handlers"></a>Predicates Attributes and Handlers</h3>
<div class="sect3">
<h4 id="introduction-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#introduction-2"></a>Introduction</h4>
<div class="paragraph">
<p>Predicates and Exchange attributes are an abstraction that allow handlers to read, write and make decisions based on
certain attributes of a request without hard coding this into the handler. These form the basis of Undertow’s text
based handler configuration format. Some examples are shown below:</p>
</div>
<div class="paragraph">
<p>Use the reverse proxy to send all requests to /reports to a different backend server:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>path-prefix('/reports') -&gt; reverse-proxy({'http://reports1.mydomain.com','http://reports2.mydomain.com'})</code></pre>
</div>
</div>
<div class="paragraph">
<p>Redirect all requests from /a to /b. The first example only redirects if there is an exact match, the later examples
match all paths that start with /a:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>path('/a') -&gt; redirect('/b')
path-prefix('/a') -&gt; redirect('/b${remaining}')
regex('/a(.*)') -&gt; set(attribute='%{o,Location}', value='/b${1}') -&gt; response-code(302)</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="exchange-attributes"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#exchange-attributes"></a>Exchange Attributes</h4>
<div class="paragraph">
<p>An exchange attribute represents the value of part of the exchange. For example the path attribute represents the
request path, the method attribute represents the HTTP. Even though these attributes can be retrieved and modified
directly this requires a handler to hard code the attribute that they wish to use. For example Undertow provides a
handler that checks an attribute against an access control list. There are lots of different attributes we may wish
to check against the ACL (e.g. username, User-Agent header, request path).</p>
</div>
</div>
<div class="sect3">
<h4 id="predicates"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#predicates"></a>Predicates</h4>
<div class="paragraph">
<p>A predicate is a function that takes a value (in this case the <code>HttpServerExchange</code>) and returns a true or false value.
This allows actions to be taken based on the return value of the predicate. In general any handler that needs to make
a boolean decision based on the exchange should use a predicate to allow for maximum flexibility.</p>
</div>
<div class="paragraph">
<p>The provided predicate handler can be used to make a decision between which handler to invoke based on the value of a
predicate.</p>
</div>
</div>
<div class="sect3">
<h4 id="programmatic-representation-of-exchange-attributes"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#programmatic-representation-of-exchange-attributes"></a>Programmatic Representation of Exchange Attributes</h4>
<div class="paragraph">
<p>An exchange attribute is represented by the <code>io.undertow.attribute.ExchangeAttribute</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="comment">/**
 * Representation of a string attribute from a HTTP server exchange.
 */</span>
<span class="directive">public</span> <span class="type">interface</span> <span class="class">ExchangeAttribute</span> {

    <span class="comment">/**
     * Resolve the attribute from the HTTP server exchange. This may return null if the attribute is not present.
     * @param exchange The exchange
     * @return The attribute
     */</span>
    <span class="predefined-type">String</span> readAttribute(<span class="directive">final</span> HttpServerExchange exchange);

    <span class="comment">/**
     * Sets a new value for the attribute. Not all attributes are writable.
     * @param exchange The exchange
     * @param newValue The new value for the attribute
     */</span>
    <span class="type">void</span> writeAttribute(<span class="directive">final</span> HttpServerExchange exchange, <span class="directive">final</span> <span class="predefined-type">String</span> newValue) <span class="directive">throws</span> ReadOnlyAttributeException;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Undertow provides implementation of a lot of attributes out of the box, most of which can be accessed using the
<code>io.undertow.attribute.ExchangeAttributes</code> utility class. Some of the attributes that are provided include request and
response headers, cookies, path, query parameters, the current user and more.</p>
</div>
</div>
<div class="sect3">
<h4 id="programmatic-representation-of-predicates"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#programmatic-representation-of-predicates"></a>Programmatic Representation of Predicates</h4>
<div class="paragraph">
<p>Predicates are represented by the <code>io.undertow.predicate.Predicate</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="comment">/**
 * A predicate.
 *
 * This is mainly uses by handlers as a way to decide if a request should have certain
 * processing applied, based on the given conditions.
 */</span>
<span class="directive">public</span> <span class="type">interface</span> <span class="class">Predicate</span> {

    <span class="comment">/**
     * Attachment key that can be used to store additional predicate context that allows the predicates to store
     * additional information. For example a predicate that matches on a regular expression can place additional
     * information about match groups into the predicate context.
     *
     * Predicates must not rely on this attachment being present, it will only be present if the predicate is being
     * used in a situation where this information may be required by later handlers.
     *
     */</span>
    AttachmentKey&lt;<span class="predefined-type">Map</span>&lt;<span class="predefined-type">String</span>, <span class="predefined-type">Object</span>&gt;&gt; PREDICATE_CONTEXT = AttachmentKey.create(<span class="predefined-type">Map</span>.class);

    <span class="type">boolean</span> resolve(<span class="directive">final</span> HttpServerExchange value);

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Undertow provides built in predicates that can be created using the <code>io.undertow.predicate.Predicates</code> utility class.
This includes basic boolean logic predicates (and, or and not), as well as other useful predicates such as path
matching (including prefix and suffix based matches), regular expression matching, contains and exists. Many of these
predicates operate on exchange attributes, so they can be used to match arbitrary parts of the exchange. The following
example demonstrates a predicate that matches any exchange that has no Content-Type header where the method is POST:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="predefined-type">Predicate</span> predicate = Predicates.and(
        Predicates.not(Predicates.exists(ExchangeAttributes.requestHeader(Headers.CONTENT_TYPE))),
        Predicates.equals(<span class="string"><span class="delimiter">"</span><span class="content">POST</span><span class="delimiter">"</span></span>, ExchangeAttributes.requestMethod()));</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="textual-representation"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#textual-representation"></a>Textual Representation</h4>
<div class="admonitionblock warning">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Undertows predicate language is still considered tech preview. Its syntax will likely change in a future version
as the language is expanded.
</td>
</tr>
</tbody></table>
</div>
<div class="paragraph">
<p>All these attributes and predicates are all well and good, but unless there is a way for the end user to configure them
without resorting to programmatic means they are not super useful. Fortunately Undertow provides a way to do just that.</p>
</div>
</div>
<div class="sect3">
<h4 id="exchange-attributes-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#exchange-attributes-2"></a>Exchange Attributes</h4>
<div class="paragraph">
<p>Exchange attributes may have up to two textual representations, a long one and a short one. The long version takes the
form %{attribute}, while the short version is a percent sign followed by a single character. A list of the built in
attributes provided by Undertow is below:</p>
</div>
<table class="tableblock frame-topbot grid-all spread">
<colgroup>
<col style="width: 33%;">
<col style="width: 33%;">
<col style="width: 33%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Short Form</th>
<th class="tableblock halign-left valign-top">Long Form</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Remote IP address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%a</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{REMOTE_IP}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Local IP address</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%A</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{LOCAL_IP}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Bytes sent, excluding HTTP headers, or <em>-</em> if no bytes were sent</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%b</code></p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Bytes sent, excluding HTTP headers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%B</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{BYTES_SENT}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Remote host name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%h</code></p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request protocol</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%H</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{PROTOCOL}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Remote logical username from identd (always returns <em>-</em>)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%l</code></p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request method</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%m</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{METHOD}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Local port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%p</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{LOCAL_PORT}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Query string (prepended with a <em>?</em> if it exists, otherwise an empty string)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%q</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{QUERY_STRING}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">First line of the request</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%r</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{REQUEST_LINE}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">HTTP status code of the response</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%s</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{RESPONSE_CODE}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Date and time, in Common Log Format format</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{DATE_TIME}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Remote user that was authenticated</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%u</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{REMOTE_USER}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Requested URL path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%U</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{REQUEST_URL}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request relative path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%R</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{RELATIVE_PATH}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Local server name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%v</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{LOCAL_SERVER_NAME}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Time taken to process the request, in millis</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%D</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{RESPONSE_TIME}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Time taken to process the request, in seconds</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%T</code></p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Current request thread name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%I</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{THREAD_NAME}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSL cypher</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{SSL_CIPHER}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSL client certificate</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{SSL_CLIENT_CERT}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">SSL session id</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{SSL_SESSION_ID}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Cookie value</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{c,cookie_name}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Query parameter</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{q,query_param_name}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Request header</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{i,request_header_name}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Response header</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>%{o,response_header_name}</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Value from the predicate context</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${name}</code></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Any tokens that do not follow one of the above patterns are assumed to be literals. For example assuming a
user name of <em>Stuart</em> and a request method of <em>GET</em> the attribute text <code>Hello %u the request method is %m</code> will give
the value <code>Hello Stuart the request method is GET</code>.</p>
</div>
<div class="paragraph">
<p>These attributes are used anywhere that text based configuration is required, e.g. specifying the log pattern in the
access log.</p>
</div>
<div class="paragraph">
<p>Some handlers may actually modify these attributes. In order for this to work the attribute must not be read only, and
must consist of only a single token from the above table.</p>
</div>
</div>
<div class="sect3">
<h4 id="textual-representation-of-predicates"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#textual-representation-of-predicates"></a>Textual Representation of Predicates</h4>
<div class="paragraph">
<p>Sometimes it is also useful to have a textual representation of a predicate. For examples when configuring a handler
in Wildfly we may want it only to run if a certain condition is met, and when doing rewrite handling we generally do
not want to re-write all requests, only a subset of them.</p>
</div>
<div class="paragraph">
<p>To this end Undertow provides a way to specify a textual representation of a predicate. In its simplest form, a
predicate is represented as <code>predicate-name[name1=value1,name2=value2]</code>.</p>
</div>
<div class="paragraph">
<p>For example, the following predicates all match POST requests:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>method(POST)
method(value=POST)
equals({%{METHOD}, POST})
equals(%m, "POST")
regex(pattern="POST", value="%m", full-match=true)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Lets examine these a bit more closely. The first one <code>method(POST)</code> uses the built in method predicate that matches
based on the method. As this predicate takes only a single parameter (that is the default parameter) it is not necessary
to explicitly specify the parameter name. Also note that POST is not quoted, quoting is only necessary if the token
contains spaces, commas or square braces.</p>
</div>
<div class="paragraph">
<p>The second example <code>method(value=POST)</code> is the same as the first, except that the parameter name is explicitly specified.</p>
</div>
<div class="paragraph">
<p>The third and fourth examples demonstrates the <em>equals</em> predicate. This predicate actually takes one parameter that is an
array, and will return true if all items in the array are equal. Arrays are generally enclosed in curly braces, however in
this case where there is a single parameter that is the default parameter the braces can be omitted.</p>
</div>
<div class="paragraph">
<p>The final examples shows the use of the regex predicate. This takes 3 parameters, the pattern to match, the value to
match against and full-match, which determines if the pattern must match the whole value or simply part of it.</p>
</div>
<div class="paragraph">
<p>Some predicates may also capture additional information about the match and store it in the predicate context. For
example the regex predicate will store the match under the key <em>0</em>, and any match groups under the key <em>1</em>, <em>2</em> etc.</p>
</div>
<div class="paragraph">
<p>These contextual values can then be retrieved by later predicates of handlers using the syntax <code>${0}</code>, <code>${1}</code> etc.</p>
</div>
<div class="paragraph">
<p>Predicates can be combined using the boolean operators <em>and</em>, <em>or</em> and not. Some examples are shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>not method(POST)
method(POST) and path-prefix("/uploads")
path-template(value="/user/{username}/*") and equals(%u, ${username})
regex(pattern="/user/(.*?)./.*", value=%U, full-match=true) and equals(%u, ${1})</code></pre>
</div>
</div>
<div class="paragraph">
<p>The first predicate will match everything except post requests. The second will match all post requests to /uploads.
The third predicate will match all requests to URL’s of the form /user/{username}/* where the username is equal to the
username of the currently logged in user. In this case the username part of the URL is captured, and the equals handler
can retrieve it using the <code>${username}</code> syntax shown above. The fourth example is the same as the third, however it uses
a regex with a match group rather than a path template.</p>
</div>
<div class="paragraph">
<p>The complete list of built in predicates is shown below:</p>
</div>
<table class="tableblock frame-topbot grid-all spread">
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Parameters</th>
<th class="tableblock halign-left valign-top">Default Parameter</th>
<th class="tableblock halign-left valign-top">Additional context</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">auth-required</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">contains</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">search: String[] (required), value: attribute (required)</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">directory</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: attribute</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">dispatcher</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: String (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">equals</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: attribute[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">exists</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: attribute (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">file</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: attribute</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-content-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: Long (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">method</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: String[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">min-content-size</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: Long (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">path: String[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path-prefix</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">path: String[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Unmatched under ${remaining}</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path-suffix</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">path: String[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">path</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path-template</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">match: attribute, value: String (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Path template elements under the name</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">regex</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">case-sensitive: Boolean, full-match: Boolean, pattern: String (required), value: attribute</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">pattern</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Match groups under number</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">secure</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="textual-representation-of-handlers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#textual-representation-of-handlers"></a>Textual Representation of Handlers</h4>
<div class="paragraph">
<p>Handlers are represented in a similar way to predicates. Handlers are predicates are combined into the Undertow predicate
language.</p>
</div>
<div class="paragraph">
<p>The general form of this language is <code>predicate -&gt; handler</code>. If the predicate evaluates to true the handler is executes.
If there is only a handler present then the handler is always executed. Handlers are executed in order and separated
by line breaks or semi colons. Curly braces can be used to create a sub grouping, with all handlers (and possibly predicates)
in the sub grouping being executed. The <em>else</em> keyword can be used to execute a different handler or sub grouping if the
predicate evaluates to false. Sub grouping can contain other predicates and sub groupings.</p>
</div>
<div class="paragraph">
<p>The <em>restart</em> handler is a special handler that will restart execution at the beginning of the predicated handler list.
The <em>done</em> handler will skip any remaining rules.</p>
</div>
<div class="paragraph">
<p>Some examples are below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>path(/skipallrules) and true -&gt; done
method(GET) -&gt; set(attribute='%{o,type}', value=get)
regex('(.*).css') -&gt; { rewrite('${1}.xcss'); set(attribute='%{o,chained}', value=true) }
regex('(.*).redirect$') -&gt; redirect('${1}.redirected')
set(attribute='%{o,someHeader}', value=always)
path-template('/foo/{bar}/{f}') -&gt; set[attribute='%{o,template}', value='${bar}')
path-template('/bar-&gt;foo') -&gt; {
    redirect(/);
} else {
    path(/some-other-path) -&gt; header(header=my-header,value=my-value)
}
regex('(.*).css') -&gt; set(attribute='%{o,css}', value='true') else set(attribute='%{o,css}', value='false');
path(/restart) -&gt; {
    rewrite(/foo/a/b);
    restart;
}</code></pre>
</div>
</div>
<table class="tableblock frame-topbot grid-all spread">
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Parameters</th>
<th class="tableblock halign-left valign-top">Default Parameter</th>
<th class="tableblock halign-left valign-top">Additional context</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">access-log</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">format: String (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">format</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">allowed-methods</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">methods: String[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">methods</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">blocking</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">byte-range</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">send-accept-ranges: boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">send-accept-ranges</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">canonical-path</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">compress</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">disable-cache</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">disallowed-methods</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">methods: String[] (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">methods</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">done</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">dump-request</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">error-file</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">file: String (required), response-codes: class [Ljava.lang.Integer; (required)</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">header</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">header: String (required), value: attribute (required)</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ip-access-control</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">acl: String[] (required), default-allow: boolean, failure-status: int</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">acl</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jvm-route</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">session-cookie-name: String, value: String (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">learning-push</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">max-age: class java.lang.Integer, max-entries: class java.lang.Integer</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">path-separator</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">proxy-peer-address</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">redirect</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: attribute (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">request-limit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">requests: int (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">requests</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">resolve-peer-name</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">resource</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">allow-listing: boolean, location: String (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">location</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">response-code</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: class java.lang.Integer (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">response-rate-limit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">bytes: class java.lang.Integer (required), time: Long (required)</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">restart</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">reverse-proxy</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">hosts: String[] (required), rewrite-host-header: Boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">hosts</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">rewrite</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value: attribute (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">value</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">set</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">attribute: attribute (required), value: attribute (required)</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ssl-headers</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">trace</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">url-decoding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">charset: String (required)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">charset</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="reverse-proxy"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#reverse-proxy"></a>Reverse Proxy</h3>
<div class="paragraph">
<p>Undertow’s reverse proxy is implemented as a handler, and as such it can be used like any other handler.</p>
</div>
<div class="paragraph">
<p>An instance of the handler can be created using the <code>io.undertow.Handlers#proxyHandler</code> method. It takes two parameters,
a <code>ProxyClient</code> instance and the next handler to invoke if the client does not know how to proxy a request (often just
a handler that returns a 404). It is also possible to specify the maximum request time, after which time a request will
be terminated.</p>
</div>
<div class="paragraph">
<p>Undertow provides two instances of <code>ProxyClient</code> (there is a third one under development that has mod_cluster support).
Note that all proxy clients use the Undertow HTTP client API. At the moment this provides support for HTTP and AJP
backends.</p>
</div>
<div class="paragraph">
<p>The provided proxy clients are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">io.undertow.server.handlers.proxy.SimpleProxyClientProvider</dt>
<dd>
<p>A proxy client that just forwards to another server. It takes the servers URI as a constructor parameter, and then will
forward all requests to the target server. Connections are maintained on a one to one basis, a connection to the front
end server results in a new connection to the back end server.</p>
</dd>
<dt class="hdlist1">io.undertow.server.handlers.proxy.LoadBalancingProxyClient</dt>
<dd>
<p>A load balancing proxy client that forwards requests to servers in a round robin fashion, unless sticky sessions have
been enabled in which case requests with a session cookie will always be forwarded to the same server.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Target servers can be added to the client using the <code>addHost</code> method, which takes the server URI to connect to and an
optional node ID to use for sticky sessions.</p>
</div>
<div class="paragraph">
<p>The load balancing proxy maintain a pool of connections to each backend server. The number of connections in the pool is
determined by the parameter <code>connectionsPerThread</code>, which specifies the maximum number of connections per IO thread (so
to get the total number of connections multiply this by the number of IO threads). The reason why this pool is maintain
by thread is to make sure that both the frontend and backend connections use the same thread, so the proxy client
does not have to deal with threading issues.</p>
</div>
<div class="paragraph">
<p>In general the client connects to servers one after the other in a round robin fashion, skipping any servers that are
either full (i.e. all connections in the pool are in use) or in a problem state (which happens if a connection attempt
fails). Servers that are in the problem state will be queried every so often (controlled by <code>problemServerRetry</code>) to see
if they have recovered.</p>
</div>
<div class="paragraph">
<p>HTTP Upgrade (including websockets) is fully supported for HTTP based backends. When a HTTP upgrade occurs the
connection is taken out of the pool and takes on a one to one relationship with the front end connection. Upgraded
connections to not count towards the backend connection limit.</p>
</div>
</div>
<div class="sect2">
<h3 id="websockets"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#websockets"></a>Websockets</h3>
<div class="paragraph">
<p>Undertow provides support for Websockets out of the box. Undertow core provides a XNIO based API,
which uses the Xnio Channel interface to provide access to the web socket at a low level.</p>
</div>
<div class="paragraph">
<p>Most users will want a higher level interface than this, and to that end Undertow also provides a JSR-356
implementation. This implementation is part of a separate jar, to use it you must make sure that you have the
<code>undertow-servlet</code> and <code>undertow-websocket-jsr</code> artifacts on your class path. Servlet support is required because the
JSR-356 API is based on the Servlet API.</p>
</div>
<div class="paragraph">
<p>For maven users the following snippet should be added to your pom.xml:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
  <span class="tag">&lt;groupId&gt;</span>io.undertow<span class="tag">&lt;/groupId&gt;</span>
  <span class="tag">&lt;artifactId&gt;</span>undertow-servlet<span class="tag">&lt;/artifactId&gt;</span>
  <span class="tag">&lt;version&gt;</span>${version.io.undertow}<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span>

<span class="tag">&lt;dependency&gt;</span>
  <span class="tag">&lt;groupId&gt;</span>io.undertow<span class="tag">&lt;/groupId&gt;</span>
  <span class="tag">&lt;artifactId&gt;</span>undertow-websockets-jsr<span class="tag">&lt;/artifactId&gt;</span>
  <span class="tag">&lt;version&gt;</span>${version.io.undertow}<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="undertow-servlet"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-servlet"></a>Undertow Servlet</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="creating-a-servlet-deployment"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#creating-a-servlet-deployment"></a>Creating a Servlet Deployment</h3>
<div class="paragraph">
<p>A simple example of how to create a Servlet deployment is the servlet example from the Undertow examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">DeploymentInfo servletBuilder = Servlets.deployment()
        .setClassLoader(ServletServer.class.getClassLoader())
        .setContextPath(<span class="string"><span class="delimiter">"</span><span class="content">/myapp</span><span class="delimiter">"</span></span>)
        .setDeploymentName(<span class="string"><span class="delimiter">"</span><span class="content">test.war</span><span class="delimiter">"</span></span>)
        .addServlets(
                Servlets.servlet(<span class="string"><span class="delimiter">"</span><span class="content">MessageServlet</span><span class="delimiter">"</span></span>, MessageServlet.class)
                        .addInitParam(<span class="string"><span class="delimiter">"</span><span class="content">message</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">Hello World</span><span class="delimiter">"</span></span>)
                        .addMapping(<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>),
                Servlets.servlet(<span class="string"><span class="delimiter">"</span><span class="content">MyServlet</span><span class="delimiter">"</span></span>, MessageServlet.class)
                        .addInitParam(<span class="string"><span class="delimiter">"</span><span class="content">message</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">MyServlet</span><span class="delimiter">"</span></span>)
                        .addMapping(<span class="string"><span class="delimiter">"</span><span class="content">/myservlet</span><span class="delimiter">"</span></span>));

DeploymentManager manager = Servlets.defaultContainer().addDeployment(servletBuilder);
manager.deploy();
PathHandler path = Handlers.path(Handlers.redirect(<span class="string"><span class="delimiter">"</span><span class="content">/myapp</span><span class="delimiter">"</span></span>))
        .addPrefixPath(<span class="string"><span class="delimiter">"</span><span class="content">/myapp</span><span class="delimiter">"</span></span>, manager.start());

Undertow server = Undertow.builder()
        .addHttpListener(<span class="integer">8080</span>, <span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>)
        .setHandler(path)
        .build();
server.start();</code></pre>
</div>
</div>
<div class="paragraph">
<p>The basic process is to create a DeploymentInfo structure (this can be done use the <code>io.undertow.servlets.Servlets</code>
utility method), add any Servlets and other information to this structure, and then deploy it to a Servlet container.</p>
</div>
<div class="paragraph">
<p>After this is deployed you can call the <code>start()</code> method on the <code>DeploymentManager</code> which returns a <code>HttpHandler</code> than
can then be installed in an Undertow server handler chain.</p>
</div>
<div class="paragraph">
<p>The <code>DeploymentInfo</code> structure has a lot of data, and most of it directly corresponds to data in web.xml so it will
not be covered in this guide, instead this will focus on the elements that are Undertow specific.</p>
</div>
<div class="sect3">
<h4 id="handler-chain-wrappers"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#handler-chain-wrappers"></a>Handler Chain Wrappers</h4>
<div class="paragraph">
<p>Hander chain wrappers allow you to insert additional <code>HttpHandlers</code> into the Servlet chain, there are three methods that
allow you to do this:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">addInitialHandlerChainWrapper()</dt>
<dd>
<p>This allows you to add a handler that is run before all other Servlet handlers. If
this handler does not delegate to the next handler in the chain it can effectively bypass the Servlet deployment.</p>
</dd>
<dt class="hdlist1">addOuterHandlerChainWrapper()</dt>
<dd>
<p>This handler is run after the servlet request context has been setup, but before any
other handlers.</p>
</dd>
<dt class="hdlist1">addInnerHandlerChainWrapper()</dt>
<dd>
<p>This handler is run after the security handlers, just before the request is dispatched to
deployment code.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="thread-setup-actions"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#thread-setup-actions"></a>Thread Setup Actions</h4>
<div class="paragraph">
<p>Thread setup actions can be added using the <code>addThreadSetupAction()</code> method, these actions will be run before a request
is dispatched to a thread, so any thread local data can be setup.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-resource-manager"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#the-resource-manager"></a>The Resource Manager</h4>
<div class="paragraph">
<p>The <code>ResourceManager</code> is used by the default servlet to serve all static resources. By modifying the resource manager
in use it is possible to pick where static resource are served from.</p>
</div>
</div>
<div class="sect3">
<h4 id="authentication-mechanisms"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#authentication-mechanisms"></a>Authentication Mechanisms</h4>
<div class="paragraph">
<p>The authentication mechanism to use is determined by the <code>LoginConfig</code> object. This maintains a list of mechanism names
and the mechanisms will be tried in order.</p>
</div>
<div class="paragraph">
<p>In addition to the built in mechanisms it is possible to add custom authentication mechanisms using the
<code>addFirstAuthenticationMechanism()</code> <code>addLastAuthenticationMechanism()</code> and <code>addAuthenticationMechanism()</code> methods.</p>
</div>
<div class="paragraph">
<p>The first and last versions of this method will both add a mechanism and add it to the <code>LoginConfig</code> object,
while the <code>addAuthenticationMechanism()</code> simply registers a factory for the given mechanism name. If you are trying
to create a general purpose authentication mechanism via a Servlet extension this is the method you should use, as it
means you can install your extension into a server for all deployments, and it will only be active for deployments
where the user has specifically selected your mechanism name in web.xml.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="servlet-extensions"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#servlet-extensions"></a>Servlet Extensions</h3>
<div class="paragraph">
<p>Servlet extensions allow you to hook into the Servlet deployment process, and modify aspect of a Servlet deployment.
In some ways they are similar to <code>ServletContainerInitializer</code> or <code>ServletContextListener</code>, however they provides much
more flexibility over what can be modified.</p>
</div>
<div class="paragraph">
<p>In order to create a ServletExtension it is necessary to implement <code>io.undertow.servlet.ServletExtension</code>, and
then add the name of your implementation class to <code>META-INF/services/io.undertow.servlet.ServletExtension</code>. When
Undertow is deploying a Servlet deployment it will load all such services from the deployments class loader, and then
invoke their <code>handleDeployment</code> method.</p>
</div>
<div class="paragraph">
<p>This method is passed an Undertow <code>DeploymentInfo</code> structure, which contains a complete and mutable description of the
deployment, my modifying this structure it is possible to change any aspect of the deployment.</p>
</div>
<div class="paragraph">
<p>The DeploymentInfo structure is the same structure that is used by the embedded API, so in effect a ServletExtension
has the same amount of flexibility that you have when using Undertow in embedded mode.</p>
</div>
<div class="paragraph">
<p>There are many possible use cases for this, a common one would be to add additional authentication mechanisms to a
deployment, or to use native Undertow handlers as part of a Servlet deployment.</p>
</div>
<div class="sect3">
<h4 id="examples"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#examples"></a>Examples</h4>
<div class="paragraph">
<p><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/deployment.html">The deployment guide</a> contains examples of how to use the <code>DeploymentInfo</code> API.</p>
</div>
<div class="paragraph">
<p><a href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/using-non-blocking-handlers-with-servlet.html">Using non-blocking handlers with Servlet deployments</a></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="using-non-blocking-handlers-with-servlet"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#using-non-blocking-handlers-with-servlet"></a>Using non-blocking handlers with servlet</h3>
<div class="paragraph">
<p>When using servlet deployments in Undertow is is possible to mix and match servlets and Undertow native handlers.</p>
</div>
<div class="paragraph">
<p>This is achieved via the <code>io.undertow.servlet.ServletExtension</code> interface. This interface allows you to customise
a servlet deployment before it is deployed, including wrapping the servlet handler chain with your own handlers.</p>
</div>
<div class="paragraph">
<p>Lets get started. First we need a <code>ServletExtension</code> implementation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">io.undertow.example.nonblocking</span>;

<span class="keyword">import</span> <span class="include">io.undertow.Handlers</span>;
<span class="keyword">import</span> <span class="include">io.undertow.server.HandlerWrapper</span>;
<span class="keyword">import</span> <span class="include">io.undertow.server.HttpHandler</span>;
<span class="keyword">import</span> <span class="include">io.undertow.server.handlers.PathHandler</span>;
<span class="keyword">import</span> <span class="include">io.undertow.servlet.ServletExtension</span>;
<span class="keyword">import</span> <span class="include">io.undertow.servlet.api.DeploymentInfo</span>;
<span class="keyword">import</span> <span class="include">io.undertow.servlet.spec.ServletContextImpl</span>;

<span class="directive">public</span> <span class="type">class</span> <span class="class">NonBlockingHandlerExtension</span> <span class="directive">implements</span> ServletExtension {
    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleDeployment(<span class="directive">final</span> DeploymentInfo deploymentInfo, <span class="directive">final</span> ServletContextImpl servletContext) {
        deploymentInfo.addInitialHandlerChainWrapper(<span class="keyword">new</span> HandlerWrapper() {
            <span class="annotation">@Override</span>
            <span class="directive">public</span> HttpHandler wrap(<span class="directive">final</span> HttpHandler handler) {
                <span class="keyword">return</span> Handlers.path()
                        .addPrefixPath(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>, handler)
                        .addPrefixPath(<span class="string"><span class="delimiter">"</span><span class="content">/hello</span><span class="delimiter">"</span></span>, <span class="keyword">new</span> HelloWorldHandler());
            }
        });
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now we need a handler:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">HelloWorldHandler</span> <span class="directive">implements</span> HttpHandler {
    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleRequest(<span class="directive">final</span> HttpServerExchange exchange) <span class="directive">throws</span> <span class="exception">Exception</span> {
        exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, <span class="string"><span class="delimiter">"</span><span class="content">text/plain</span><span class="delimiter">"</span></span>);
        exchange.getResponseSender().send(<span class="string"><span class="delimiter">"</span><span class="content">Hello World</span><span class="delimiter">"</span></span>);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>We now need to register this extension. This uses to standard java service loader mechanism, so we need to create a
<code>WEB-INF/classes/META-INF/services/io.undertow.servlet.ServletExtension</code> file that contains the name of our extension
class.</p>
</div>
<div class="paragraph">
<p>Now when you deploy your war to Wildfly you should be able to navigate to <code>/mywar/hello</code> and your custom handler will be
invoked.</p>
</div>
<div class="paragraph">
<p>Lets see exactly what is going on here. When the deployment is about to deploy the <code>handleDeployment</code> method is
invoked. This method is passed the <code>io.undertow.servlet.api.DeploymentInfo</code> structure, that contains a complete
description of the deployment. One of the things that this contains is a list of handler chain wrappers. These wrappers
allow you to add additional handlers before the servlet handler.</p>
</div>
<div class="paragraph">
<p>In our wrapper we create an <code>io.undertow.server.handlers.PathHandler</code>, which is a handler provided by undertow that
maps handlers to paths. We register two different handlers into the path handler, our custom handler under <code>/hello</code>,
and the servlet handler under <code>/</code>. These paths are relative to the root of the servlet context (techinically they are
relative to the last resolved path, so if you chain two path handlers together the second paths will be resolved relative
to the first one).</p>
</div>
<div class="paragraph">
<p>In our handler we simply set a Content-Type header and then send a "Hello World" response via async IO.</p>
</div>
<div class="sect3">
<h4 id="a-slightly-more-complex-example"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#a-slightly-more-complex-example"></a>A slightly more complex example</h4>
<div class="paragraph">
<p>Say we are serving up an application, and we decide that we would like to serve all our <code>.js</code> and <code>.css</code> files using an
async handler, as we want to avoid the overhead of a servlet request.</p>
</div>
<div class="paragraph">
<p>To do this we are going to create a handler that checks the extension on the incoming request, and if it is <code>.js</code> or
<code>.css</code> then it will serve the file directly, bypassing servlet all together.</p>
</div>
<div class="admonitionblock warning">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
This will bypass all servlet handlers, including security handlers, so security rules will not be applied for
these handlers.
</td>
</tr>
</tbody></table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">NonBlockingHandlerExtension</span> <span class="directive">implements</span> ServletExtension {
    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> handleDeployment(<span class="directive">final</span> DeploymentInfo deploymentInfo, <span class="directive">final</span> ServletContextImpl servletContext) {
        deploymentInfo.addInitialHandlerChainWrapper(<span class="keyword">new</span> HandlerWrapper() {
            <span class="annotation">@Override</span>
            <span class="directive">public</span> HttpHandler wrap(<span class="directive">final</span> HttpHandler handler) {

                <span class="directive">final</span> ResourceHandler resourceHandler = <span class="keyword">new</span> ResourceHandler()
                        .setResourceManager(deploymentInfo.getResourceManager());

                PredicateHandler predicateHandler = <span class="keyword">new</span> PredicateHandler(Predicates.suffixs(<span class="string"><span class="delimiter">"</span><span class="content">.css</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">.js</span><span class="delimiter">"</span></span>), resourceHandler, handler);

                <span class="keyword">return</span> predicateHandler;
            }
        });
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Lets go through this line by line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">final</span> ResourceHandler resourceHandler = <span class="keyword">new</span> ResourceHandler()
    .setResourceManager(deploymentInfo.getResourceManager());</code></pre>
</div>
</div>
<div class="paragraph">
<p>A resource handler is a handler provided by Undertow that serves resources from a resource manager. This is basically just
an abstraction that allows us to re-use the file serving code no matter where a file in coming from. For example undertow
provides several default resource manager implementations:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">io.undertow.server.handlers.resource.FileResourceManager</dt>
<dd>
<p>A resource manager that serves files from the file system</p>
</dd>
<dt class="hdlist1">io.undertow.server.handlers.resource.ClassPathResourceManager</dt>
<dd>
<p>A resource manager that serves files from the class path</p>
</dd>
<dt class="hdlist1">io.undertow.server.handlers.resource.CachingResourceManager</dt>
<dd>
<p>A resource manger that wraps another resource manger, and provides caching.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>You do not need to worry about what type of resource manager is in use here, all you need to know is that this is the
resource manager that is being used by the default servlet, so serving files from this resource manager will mirror
the behaviour of the default servlet.</p>
</div>
<div class="paragraph">
<p>We now need to wire up our resource handler so it is only used for <code>.js</code> and <code>.css</code>. We could simply write a handler
that checks the file extension and delegates accordingly, however Undertow already provides us with one:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java">PredicateHandler predicateHandler = <span class="keyword">new</span> PredicateHandler(Predicates.suffixs(<span class="string"><span class="delimiter">"</span><span class="content">.css</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">.js</span><span class="delimiter">"</span></span>), resourceHandler, handler);</code></pre>
</div>
</div>
<div class="paragraph">
<p>A <code>PredicateHandler</code> chooses between two different handlers based on the result of a predicate that is applied to the
exchange. In this case we are using a suffix predicate, that will return <code>true</code> if the request ends with <code>.js</code> or <code>.css</code>.</p>
</div>
<div class="paragraph">
<p>When this predicate returns true our resource handler will be invoked, otherwise the request will be delegated to the servlet
container as normal.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="servlet-security"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#servlet-security"></a>Servlet Security</h3>
<div class="paragraph">
<p>As well as support for the standard servlet spec required authentication mechanisms, Undertow also allows you to create
your own mechanisms, and provides an easy way to make the accessible to an end user.</p>
</div>
<div class="sect3">
<h4 id="securing-a-servlet-deployment"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#securing-a-servlet-deployment"></a>Securing a Servlet Deployment</h4>
<div class="paragraph">
<p>Undertow provides full support for all security constructs specified in the Servlet specification. These are configured
via the DeploymentInfo structure, and in general closely mirror the corresponding structures as defined by annotations
or <code>web.xml</code>. These structures are not detailed fully here, but are covered by the relevant javadoc.</p>
</div>
<div class="paragraph">
<p>If you are using Wildfly then then it is possible to configure multiple mechanisms using <code>web.xml</code>, by listing the
mechanism names separated by commas. It is also possible to set mechanism properties using a query string like syntax.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml"><span class="tag">&lt;auth-method&gt;</span>BASIC?silent=true,FORM<span class="tag">&lt;/auth-method&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The mechanisms will be tried in the order that they are listed. In the example silent basic auth will be tried first,
which is basic auth that only takes effect if an <code>Authorization</code> header is present. If no such header is present then
form auth will be used instead. This will allow programatic clients to use basic auth, while users connecting
via a browser can use form based auth.</p>
</div>
<div class="paragraph">
<p>The built it list of mechanisms and the properties they take are as follows:</p>
</div>
<table class="tableblock frame-topbot grid-all spread">
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Mechanism Name</th>
<th class="tableblock halign-left valign-top">Options</th>
<th class="tableblock halign-left valign-top">Notes</th>
<th class="tableblock halign-left valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">BASIC</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">silent (true/false), charset, user-agent-charsets</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>silent</code> mode means that a challenge will only be issued if an <code>Authorization</code> header with invalid credentials is present. If this header is not present this auth method will never be used. <code>charset</code> specifies the default charset to use for decoding usernames and passwords. <code>user-agent-charsets</code> is a comma seperated list of the form <code>pattern,charset,pattern,charset,...</code> that allows you to change the charset used for decoding based on the browser user agent string. If the regex matches the requests user agent then the specified charset will be used instead.</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">FORM</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">CLIENT-CERT</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">DIGEST</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">EXTERNAL</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Used when authentication is being done by a front end such as httpd</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="selecting-an-authentication-mechanism"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#selecting-an-authentication-mechanism"></a>Selecting an Authentication Mechanism</h4>
<div class="paragraph">
<p>The authentication mechanism is specified via the <code>io.undertow.servlet.api.LoginConfig</code> object that can be added using
the method <code>DeploymentInfo.setLoginConfig(LoginConfig config)</code>. This object contains an ordered list of mechanism names.
The Servlet specification only allows you to specify a single mechanism name, while Undertow allows as many as you want
(if you are using Wildfly you can make use of this by using a comma separated list of names in web.xml, and pass
properties using a query string like syntax, for example <code>BASIC?silent=true,FORM</code>).</p>
</div>
<div class="paragraph">
<p>The mechanisms are standard Undertow <code>AuthenticationMechanism</code> implementations, and it should be noted that not all
mechanisms are compatible. For example trying to combine FORM and BASIC does not work, just because they both require
a different response code. Combining FORM and silent BASIC will work just fine however (silent basic auth means that
if the user agent provides an <code>Authorization:</code> header then BASIC auth will be used, however if this header is not
present then no action will be taken. This allows scripts to use basic auth, while browsers can use form).</p>
</div>
<div class="paragraph">
<p>When adding the mechanism name to the <code>LoginConfig</code> structure it is also possible to specify a property map. Custom
authentication mechanisms may use these properties however they wish. The only built in mechanism that makes use of this
mechanism is basic auth, which if passed <code>Collections.singletonMap("silent", "true")</code> will enable silent mode as
described above.</p>
</div>
<div class="paragraph">
<p>The built in mechanisms are FORM, DIGEST, CLIENT_CERT and BASIC.</p>
</div>
</div>
<div class="sect3">
<h4 id="adding-a-custom-authentication-mechanism"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#adding-a-custom-authentication-mechanism"></a>Adding a Custom Authentication Mechanism</h4>
<div class="paragraph">
<p>Custom authentication mechanisms are added using the Undertow <code>ServletExtension</code> mechanism. This provides a way
to hook into the Undertow deployment process, and add any additional mechanisms.</p>
</div>
<div class="paragraph">
<p>These extensions are discovered via the standard META-INF/services discovery mechanism, so if you have a jar that
provides a custom authentication mechanism all that should be required is to add this jar to your deployment and
then specify the mechanism name in web.xml.</p>
</div>
<div class="paragraph">
<p>For more info see the <a href="servlet-extensions.html:">Servlet extensions guide</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="advanced-servlet-use-cases"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#advanced-servlet-use-cases"></a>Advanced Servlet Use Cases</h3>
<div class="paragraph">
<p>As well as allowing you to add all the standard Servlet constructs that you would expect (such as Servlets, Filters
etc), Undertow also allows you to customise your deployment in a number of ways. This section details these additional
options.</p>
</div>
<div class="admonitionblock note">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This section does not cover all the different options available in the DeploymentInfo structure. For a complete
reference please refer to the javadoc.
</td>
</tr>
</tbody></table>
</div>
<div class="sect3">
<h4 id="inserting-custom-handlers-into-the-servlet-handler-chain"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#inserting-custom-handlers-into-the-servlet-handler-chain"></a>Inserting Custom Handlers into the Servlet Handler Chain</h4>
<div class="paragraph">
<p>It is possible to insert customer handlers into various parts of the servlet handler chain. This is done by adding a
<code>io.undertow.server.HandlerWrapper</code> to the DeploymentInfo structure. This will be called at deployment time and allows
you to wrap the existing handler.</p>
</div>
<div class="paragraph">
<p>There are three possible places where a handler can be inserted:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Before the Servlet Chain</dt>
<dd>
<p>This happens before any Servlet handlers are invoked, and handlers inserted here have the option of completly bypassing
Servlet altogether. Some possible use cases include serving static files directly without any Servlet overhead, or
performing some kind of request re-writing before Servlet is invoked. To add a wrapper here use
<code>DeploymentInfo.addInitialHandlerChainWrapper(HandlerWrapper wrapper)</code>.</p>
</dd>
<dt class="hdlist1">After the Servlet Initial Handler</dt>
<dd>
<p>This happens after the initial Servlet handler is invoked. The request has been dispatched to a worker thread,
request and response objects have been created, the target servlet has been resolved and all relevant info has been
attached to the exchange as part of the <code>ServletRequestContext</code>. No security handlers have been invoked at this stage.
To add a wrapper here use <code>DeploymentInfo.addOuterHandlerChainWrapper(HandlerWrapper wrapper)</code>.</p>
</dd>
<dt class="hdlist1">After the Security Initial Handlers</dt>
<dd>
<p>This happens after the Security handlers have been invoked, before the request is dispatched to the first Filter or
Servlet.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>To add a wrapper here use <code>DeploymentInfo.addInnerHandlerChainWrapper(HandlerWrapper wrapper)</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="thread-setup-actions-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#thread-setup-actions-2"></a>Thread Setup Actions</h4>
<div class="paragraph">
<p>Thread setup actions allow you to perform tasks before and after control is dispatched to user code. The most common
use for this is to set up thread local contexts. For example a server might want to setup the appropriate JNDI contexts
before control is passed to user code, so make sure the code has access to the correct <code>java:comp</code> context.</p>
</div>
<div class="paragraph">
<p>Thread setup actions can be added using <code>DeploymentInfo.addThreadSetupAction(ThreadSetupAction action)</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="ignore-flush"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#ignore-flush"></a>Ignore Flush</h4>
<div class="paragraph">
<p>In Servlet code it is common to see code that looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SomeServlet</span> <span class="directive">extends</span> HttpServlet {

    <span class="annotation">@Override</span>
    <span class="directive">protected</span> <span class="type">void</span> doGet(<span class="directive">final</span> HttpServletRequest req, <span class="directive">final</span> HttpServletResponse resp) <span class="directive">throws</span> ServletException, <span class="exception">IOException</span> {
            <span class="predefined-type">OutputStream</span> stream = resp.getOutputStream();

            <span class="comment">//do stuff</span>

            stream.flush();
            stream.close();
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>While this seems reasonable at first glace it is actually terrible from a performance point of view. The <code>flush()</code> call
before the <code>close()</code> call forces content to be written to the client, which will generally force chunked encoding. The
following <code>close()</code> call then writes out the chunk terminator, resulting in another write to the socket. This means that
a response that could otherwise have been written out using a single write call using a fixed content length now takes
two and uses chunked encoding.</p>
</div>
<div class="paragraph">
<p>To work around this poor practice Undertow provides an option to ignore flushes on the ServletOutputStream. This can
be activated by calling <code>DeploymentInfo.setIgnoreFlush(true)</code>. Even though <code>flush()</code> will no longer flush to the
client when this is enabled Undertow will still treat the response as commited and not allow modification of the headers.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jsp"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#jsp"></a>JSP</h3>
<div class="paragraph">
<p>JSP can be used in Undertow through the use of the <a href="https://github.com/undertow-io/jastow">Jastow</a> project, which is
a fork of Apache Jasper for use in Undertow (note that <em>fork</em> is used very loosely here, it is basically just Jasper with
its Tomcat dependencies removed).</p>
</div>
<div class="paragraph">
<p>Jasper provides all its functionality though a Servlet, as a result can be added to a standard Undertow servlet deployment
by adding the JSP servlet to the <em>*.jsp</em> mapping.</p>
</div>
<div class="paragraph">
<p>There are also some additional context parameters that JSP requires, and Jastow provides a helper class to set these up.</p>
</div>
<div class="paragraph">
<p>An example of how to set up a JSP deployment is shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight nowrap"><code data-lang="xml">final PathHandler servletPath = new PathHandler();
final ServletContainer container = ServletContainer.Factory.newInstance();

DeploymentInfo builder = new DeploymentInfo()
        .setClassLoader(SimpleJspTestCase.class.getClassLoader())
        .setContextPath("/servletContext")
        .setClassIntrospecter(TestClassIntrospector.INSTANCE)
        .setDeploymentName("servletContext.war")
        .setResourceManager(new TestResourceLoader(SimpleJspTestCase.class))
        .addServlet(JspServletBuilder.createServlet("Default Jsp Servlet", "*.jsp"));
JspServletBuilder.setupDeployment(builder, new HashMap<span class="tag">&lt;String</span><span class="error">,</span> <span class="attribute-name">JspPropertyGroup</span><span class="tag">&gt;</span>(), new HashMap<span class="tag">&lt;String</span><span class="error">,</span> <span class="attribute-name">TagLibraryInfo</span><span class="tag">&gt;</span>(), new MyInstanceManager());

DeploymentManager manager = container.addDeployment(builder);
manager.deploy();
servletPath.addPrefixPath(builder.getContextPath(), manager.start());</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that JSP tags are created using an instance of the Jasper <code>InstanceManager</code> interface. If you do not require injection
into tags then this interface can simply create a new instance using reflection.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="undertow-js"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-js"></a>Undertow.js</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="undertow-js-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-js-2"></a>Undertow.js</h3>
<div class="paragraph">
<p>Undertow.js is a standalone project that makes it easy to write server side Javascript with Undertow. It supports the
following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Java EE integration, including dependency injection</p>
</li>
<li>
<p>REST</p>
</li>
<li>
<p>Templates</p>
</li>
<li>
<p>Declarative security</p>
</li>
<li>
<p>Filters</p>
</li>
<li>
<p>Websockets</p>
</li>
<li>
<p>Hot reload</p>
</li>
<li>
<p>JDBC</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The functionality is intended to be used as part of a Servlet deployment. It is designed to make it easy to mix Javascript
and Java EE backend functionality, allowing you to quickly create a front end in Javascript while still using Java EE for
all the heavy lifting.</p>
</div>
<div class="paragraph">
<p>An overview of the functionality can be found at <a href="http://wildfly.org/news/2015/08/10/Javascript-Support-In-Wildfly/" class="bare">http://wildfly.org/news/2015/08/10/Javascript-Support-In-Wildfly/</a>.
Some simple examples can be found at <a href="https://github.com/stuartwdouglas/undertow.js-examples" class="bare">https://github.com/stuartwdouglas/undertow.js-examples</a>.</p>
</div>
<div class="sect3">
<h4 id="getting-started"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#getting-started"></a>Getting Started</h4>
<div class="paragraph">
<p>First you need to include the latest Undertow.js in your application. If you are using Wildfly 10 this is not necessary,
as Wildfly 10 provides this functionality out of the box. If you are using maven you can include the following in your
<code>pom.xml</code> :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
        <span class="tag">&lt;groupId&gt;</span>io.undertow.js<span class="tag">&lt;/groupId&gt;</span>
        <span class="tag">&lt;artifactId&gt;</span>undertow-js<span class="tag">&lt;/artifactId&gt;</span>
        <span class="tag">&lt;version&gt;</span>1.0.0.Alpha3<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Otherwise you can download the jars from link:http://mvnrepository.com/artifact/io.undertow.js/undertow-js .</p>
</div>
<div class="paragraph">
<p>Once you have Undertow.js you need to tell it where to find your javascript files.
To do this we create a file <code>WEB-INF/undertow-scripts.conf</code>. In this file you list your server side JavaScript files,
one per line. These files will be executed in the order specified.</p>
</div>
<div class="paragraph">
<p>Note that even though the server JavaScript files are located in the web context, the JavaScript integration will
not allow them to be served. If a user requests a server side JS file a 404 will be returned instead.</p>
</div>
<div class="paragraph">
<p>We can now create a simple endpoint. Create a javascript file, add it to <code>undertow-scripts.conf</code> and add the following
contents:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>
    .onGet(<span class="string"><span class="delimiter">"</span><span class="content">/hello</span><span class="delimiter">"</span></span>,
        {<span class="key">headers</span>: {<span class="key"><span class="delimiter">"</span><span class="content">content-type</span><span class="delimiter">"</span></span>: <span class="string"><span class="delimiter">"</span><span class="content">text/plain</span><span class="delimiter">"</span></span>}},
        [<span class="keyword">function</span> (<span class="predefined">$exchange</span>) {
            <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="content">Hello World</span><span class="delimiter">"</span></span>;
        }])</code></pre>
</div>
</div>
<div class="paragraph">
<p>Accessing the <code>/hello</code> path inside your deployment should now return a <em>Hello World</em> response. Note that this path is
relative to the context root, so if your deployment is <code>example.war</code> and your server is running on port 8080 the handler
will be installed at <code>http://localhost:8080/example/hello</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="basic-concepts"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#basic-concepts"></a>Basic concepts</h4>
<div class="paragraph">
<p>The $undertow global provides the main functionality of an Undertow.js application. When your scripts are executed they
invoke methods on this object to register HTTP and Websocket handlers. Incoming requests for the application will be
checked against these handlers, and if they match the relevant javascript will be run to handle the request. If there
is no matches the request is forwarded to the Servlet container as normal.</p>
</div>
<div class="paragraph">
<p>If a file is modified and hot deployment is enabled the Nashorn engine is discarded, a new engine is created and all scripts
are executed again to re-set up the handlers.</p>
</div>
</div>
<div class="sect3">
<h4 id="http-endpoints"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#http-endpoints"></a>HTTP Endpoints</h4>
<div class="paragraph">
<p>To register a handler for a HTTP endpoint you can use one of the following methods</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>onGet</code></p>
</li>
<li>
<p><code>onPost</code></p>
</li>
<li>
<p><code>onPut</code></p>
</li>
<li>
<p><code>onDelete</code></p>
</li>
<li>
<p><code>onRequest</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p><code>onRequest</code> takes the method name as a first parameter, otherwise its usage is the same as the others. These methods can
accept a variable number of parameters.</p>
</div>
<div class="paragraph">
<p>Note that all methods on <code>$undertow</code> are fluent, they return the same object so they can be chained together.</p>
</div>
<div class="paragraph">
<p>There are a number of different forms that can be used to invoke these methods, they are all covered below.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, <span class="keyword">function</span>(<span class="predefined">$exchange</span>) {...})
<span class="predefined">$undertow</span>.onRequest(<span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, <span class="keyword">function</span>(<span class="predefined">$exchange</span>) {...})

<span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, [<span class="keyword">function</span>(<span class="predefined">$exchange</span>) {...}])
<span class="predefined">$undertow</span>.onRequest(<span class="string"><span class="delimiter">"</span><span class="content">GET</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, [<span class="keyword">function</span>(<span class="predefined">$exchange</span>) {...}])</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is the simplest usage, which consists of a path and a handler function to register under this path. Both the usages
shown above are identical. Future examples will not show the <code>onRequest</code> version, as with the exception of the method name
it is identical.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, [<span class="string"><span class="delimiter">'</span><span class="content">cdi:myBean</span><span class="delimiter">'</span></span>, <span class="keyword">function</span>(<span class="predefined">$exchange</span>, myBean) {...}])</code></pre>
</div>
</div>
<div class="paragraph">
<p>The example above shows the use of dependency injection. If a list is passed as the last argument instead of a function
then it is assumed to be a dependency injection list. It should consist of dependency names, followed by the handler
function as the last element in the list. When the handler is invoked these items will be resolved, and passed into the
method as parameters. The process is covered in more detail later.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path/{name}</span><span class="delimiter">"</span></span>, <span class="keyword">function</span>(<span class="predefined">$exchange</span>) {...})</code></pre>
</div>
</div>
<div class="paragraph">
<p>This example shoes the use a of path template instead of a hard coded path. The path parameter <code>name</code> can be accessed
using the syntax <code>$exchange.params('name')</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, {headers={<span class="key"><span class="delimiter">'</span><span class="content">Content-Type</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">text/plain</span><span class="delimiter">'</span></span>}}, <span class="keyword">function</span>(<span class="predefined">$exchange</span>) {...})</code></pre>
</div>
</div>
<div class="paragraph">
<p>This usage includes an extra parameter, the metadata map. The usage of this is covered in more detail in the relevant
sections, however the allowed values in this map are as follows:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">template</dt>
<dd>
<p>A template that should be applied using the data that is returned from the handler function.</p>
</dd>
<dt class="hdlist1">template_type</dt>
<dd>
<p>The template engine that should be used to render the template.</p>
</dd>
<dt class="hdlist1">headers</dt>
<dd>
<p>A map of response headers to add to the response.</p>
</dd>
<dt class="hdlist1">predicate</dt>
<dd>
<p>An Undertow predicate string that determines if this handler should actually be executed.</p>
</dd>
<dt class="hdlist1">roles_allowed</dt>
<dd>
<p>A list of roles that are allowed to access this handler. This uses the security configuration of the servlet deployment.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>It is possible to set default values for all of these values using the <code>$undertow.setDefault()</code> method. For example to
set a content type header for all handlers you would do <code>$undertow.setDefault('headers', {'Content-Type': application/json})</code>.
These defaults only take effect if the corresponding metadata item is not set on the handler.</p>
</div>
<div class="paragraph">
<p>Handler functions can return a value. How this value is interpreted depends on the handler and what is returned. If
the <code>template</code> parameter is specified in the metadata map then this return value is used as the data object for the template.
Otherwise if the return value is a string it is sent to the client as the entity body, otherwise the return value will
be converted into JSON using JSON.stringify() and the resulting JSON sent to the client.</p>
</div>
</div>
<div class="sect3">
<h4 id="the-exchange-object"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#the-exchange-object"></a>The exchange object</h4>
<div class="paragraph">
<p>The first parameter of any handler is the exchange object. This object is a wrapper around the Undertow <code>HttpServerExchange</code>,
that makes it easier to use if from within Javascript. If you want to access the actual underlying object for whatever
reason you can do so with the <code>$underlying</code> property (this applies to all wrapper objects used by Undertow.js, if the
wrapper does not meet your needs you can get the underlying java object and invoke it directly).</p>
</div>
<div class="paragraph">
<p>The exchange object provides the following methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$exchange</span>.requestHeaders(<span class="string"><span class="delimiter">'</span><span class="content">User-Agent</span><span class="delimiter">'</span></span>);             <span class="comment">//gets the user agent request header</span>
<span class="predefined">$exchange</span>.requestHeaders(<span class="string"><span class="delimiter">'</span><span class="content">User-Agent</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">foo 1.0</span><span class="delimiter">'</span></span>);  <span class="comment">//sets the user agent request header</span>
<span class="predefined">$exchange</span>.requestHeaders();                         <span class="comment">//get the request headers map</span>

<span class="predefined">$exchange</span>.responseHeaders(<span class="string"><span class="delimiter">'</span><span class="content">Content-Length</span><span class="delimiter">'</span></span>);        <span class="comment">//gets the content-length response header</span>
<span class="predefined">$exchange</span>.responseHeaders(<span class="string"><span class="delimiter">'</span><span class="content">Content-Length</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">100</span><span class="delimiter">'</span></span>); <span class="comment">//sets the content length response header</span>
<span class="predefined">$exchange</span>.responseHeaders();                        <span class="comment">//gets the response header map</span>

<span class="predefined">$exchange</span>.send(<span class="string"><span class="delimiter">"</span><span class="content">data</span><span class="delimiter">"</span></span>);                             <span class="comment">//sends the given string as the response body, and ends the exchange when done</span>
<span class="predefined">$exchange</span>.send(<span class="integer">404</span>, <span class="string"><span class="delimiter">"</span><span class="content">not found</span><span class="delimiter">"</span></span>);                   <span class="comment">//sets the given response code, and sends the response body, ending the exchange when done</span>

<span class="predefined">$exchange</span>.redirect(<span class="string"><span class="delimiter">"</span><span class="content">http://www.example.org/index.php</span><span class="delimiter">"</span></span>); <span class="comment">//redirects to the given location</span>

<span class="predefined">$exchange</span>.status();                                 <span class="comment">//returns the current status code</span>
<span class="predefined">$exchange</span>.status(<span class="integer">404</span>);                              <span class="comment">//sets the current status code</span>

<span class="predefined">$exchange</span>.endExchange();                            <span class="comment">//ends the current exchange</span>

<span class="predefined">$exchange</span>.param(<span class="string"><span class="delimiter">"</span><span class="content">name</span><span class="delimiter">"</span></span>);                            <span class="comment">//gets the first query or path parameter with the specified name</span>

<span class="predefined">$exchange</span>.params(<span class="string"><span class="delimiter">"</span><span class="content">names</span><span class="delimiter">"</span></span>);                          <span class="comment">//gets a list of the query or path parameters with the specified name</span>

<span class="predefined">$exchange</span>.session();                                <span class="comment">//returns the servlet HTTPSession object</span>
<span class="predefined">$exchange</span>.request();                                <span class="comment">//returns the servlet request object</span>
<span class="predefined">$exchange</span>.response();                               <span class="comment">//returns the servlet response object</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="injection"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#injection"></a>Injection</h4>
<div class="paragraph">
<p>As shown above Undertow.js supports injection into handler functions. To perform an injection pass the name of the injection
in a list with the handler function, as shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, [<span class="string"><span class="delimiter">'</span><span class="content">$entity:json</span><span class="delimiter">'</span></span>, <span class="keyword">function</span>(<span class="predefined">$exchange</span>, entity) {...}])</code></pre>
</div>
</div>
<div class="paragraph">
<p>The injection mechanism is pluggable, and in general injections follow the form <code>type:name</code>. The following injection types
are supported out of the box:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">$entity</dt>
<dd>
<p>This allows you to inject the request body. It supports the types <code>string</code>, <code>json</code> and <code>form</code>. <code>$entity:string</code> will inject
the entity as a string, <code>$entity:json</code> will parse the entity as JSON and deliver it as a JavaScript object, and <code>$entity:form</code>
will inject form encoded (or multipart) data.</p>
</dd>
<dt class="hdlist1">jndi</dt>
<dd>
<p>This will inject whatever object is at the specified JNDI location. For example <code>jndi:java:jboss/datasources/ExampleDS</code> will
inject the Wildfly default datasource (actually it will inject a javascript wrapper of the datasource, more on that later).</p>
</dd>
<dt class="hdlist1">cdi</dt>
<dd>
<p>This will inject a <code>@Named</code> CDI bean with the given name.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>It is possible to create aliases for commonly used injections. You can do this by calling the <code>$undertow.alias()</code> function,
for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.alias(<span class="string"><span class="delimiter">"</span><span class="content">ds</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">jndi:java:jboss/datasources/ExampleDS</span><span class="delimiter">"</span></span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that alises can not have a type specifier.</p>
</div>
<div class="paragraph">
<p>Note that this injection support is pluggable, and can be extended by implementing <code>io.undertow.js.InjectionProvider</code>,
and adding the implementing class to <code>META-INF/services/io.undertow.js.InjectionProvider</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="wrapper-objects-and-jdbc"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#wrapper-objects-and-jdbc"></a>Wrapper Objects and JDBC</h4>
<div class="paragraph">
<p>When injecting JDBC data sources Undertow does not inject the actual datasource, but a JavaScript wrapper object.
To get the underlying data source you can refer to the wrappers <code>$underlying</code> property.</p>
</div>
<div class="paragraph">
<p>The wrapper object has the following methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript">ds.query(<span class="string"><span class="delimiter">"</span><span class="content">UPDATE ...</span><span class="delimiter">"</span></span>);             <span class="comment">//executes a query, and returns the number of rows affected</span>
ds.select(<span class="string"><span class="delimiter">"</span><span class="content">SELECT * from ...</span><span class="delimiter">"</span></span>);     <span class="comment">//executes a select query, and returns an array of maps as the result</span>
ds.selectOne(<span class="string"><span class="delimiter">"</span><span class="content">SELECT * from ...</span><span class="delimiter">"</span></span>);  <span class="comment">//executes a select query, and a single map as the result</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that this wrapper mechanism is pluggable, and can be extended by adding a function to the $undertow.injection_wrappers
array. This function takes the original object and returns the wrapped result.</p>
</div>
</div>
<div class="sect3">
<h4 id="wrappers-filters"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#wrappers-filters"></a>Wrappers (Filters)</h4>
<div class="paragraph">
<p>It is possible to register <em>wrappers</em>, which act similarly to a Servlet Filter. These can intercept requests before they
reach a handler, allowing you to apply cross cutting logic such as transactions or logging. Note that these wrappers only
apply to javascript handlers, if a request is not targeted at a handler they will not be invoked.</p>
</div>
<div class="paragraph">
<p>To register a wrapper you call the <code>$undertow.wrapper()</code> function as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.wrapper(<span class="string"><span class="delimiter">"</span><span class="content">path-suffix['.html']</span><span class="delimiter">"</span></span>, [<span class="string"><span class="delimiter">"</span><span class="content">cdi:myBean</span><span class="delimiter">"</span></span>,<span class="keyword">function</span>(<span class="predefined">$exchange</span>, <span class="predefined">$next</span>, myBean) {
        <span class="comment">//do stuff</span>
        <span class="predefined">$next</span>();
    }])</code></pre>
</div>
</div>
<div class="paragraph">
<p>The first optional parameter is an Undertow predicate string, that controls when the wrapper will be invoked (in this
case for all .html files). The next argument is an injection list. This works in a similar way to handlers, however
this function takes two parameters in addition to any injected one. The $next parameter is a function that should be
invoked to invoke the next wrapper or handler in the chain.</p>
</div>
</div>
<div class="sect3">
<h4 id="templates"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#templates"></a>Templates</h4>
<div class="paragraph">
<p>It is possible to use template engines to do server side rendering. This mechanism is pluggable, out of the box the <em>mustache</em>
and <em>freemarker</em> template engines are supported, with <em>mustache</em> being the default. This is controlled by the <em>template_type</em>
entry in the metadata map, and the default can be changed by calling <code>$undertow.setDefault('template_type', 'freemarker');</code>.</p>
</div>
<div class="paragraph">
<p>To use a template all that is requires is to specify the template name in the metadata map when registering a handler, and
then return the data object that you wish to use to render the template:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/template</span><span class="delimiter">"</span></span>, {<span class="key">template</span>: test.html}, <span class="keyword">function</span>(<span class="predefined">$exchange</span>) {
    <span class="keyword">return</span> {<span class="key">message</span>: <span class="string"><span class="delimiter">"</span><span class="content">Hello World</span><span class="delimiter">"</span></span>};
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>After the handler function has been installed, the template is rendered with the provided data and sent to the client.</p>
</div>
<div class="paragraph">
<p>The template mechanism is pluggable, new engines can be added by implementing <code>io.undertow.js.templates.TemplateProvider</code>
and adding the implementation class to <code>META-INF/services/io.undertow.js.templates.TemplateProvider</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="security-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#security-2"></a>Security</h4>
<div class="paragraph">
<p>It is possible to use declarative security by specifying the allowed roles in the metadata map as an array under <code>roles_allowed</code>.
The security settings of the Servlet application are used to authenticate the user and perform the check</p>
</div>
<div class="paragraph">
<p>The special role <code>**</code> refers to any authenticated user.</p>
</div>
<div class="paragraph">
<p>An example is shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.onGet(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, {<span class="key">roles_allowed</span>: [<span class="string"><span class="delimiter">'</span><span class="content">admin</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">user</span><span class="delimiter">'</span></span>]}, <span class="keyword">function</span>(<span class="predefined">$exchange</span>) { });</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="websockets-2"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#websockets-2"></a>WebSockets</h4>
<div class="paragraph">
<p>To register a WebSocket endpoint you can invoke the <code>$undertow.websocket()</code> method as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$undertow</span>.websocket(<span class="string"><span class="delimiter">"</span><span class="content">/path</span><span class="delimiter">"</span></span>, <span class="keyword">function</span>(connection) { });</code></pre>
</div>
</div>
<div class="paragraph">
<p>This connection object is a wrapper around an Undertow <code>WebSocketConnection</code>. It supports the following methods and properties:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript">con.send(data);                     <span class="comment">//sends a websocket message</span>
con.<span class="function">onText</span> = <span class="keyword">function</span>(data){};      <span class="comment">//set the onText handler function</span>
con.<span class="function">onBinary</span> = <span class="keyword">function</span>(data){};    <span class="comment">//sets the onBinary handler function</span>
con.<span class="function">onClose</span> = <span class="keyword">function</span>(message){};  <span class="comment">//sets the close message handler function</span>
con.<span class="function">onError</span> = <span class="keyword">function</span>(error){};    <span class="comment">//sets the error handing function</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The behaviour of the <code>send()</code> function varies depending on the argument. If a string is passed in the string is sent as a
text message. If an ArrayBuffer is passed in the data will be sent as a binary message. Otherwise the object will be converted
into JSON and the result sent to the client as a text message.</p>
</div>
<div class="paragraph">
<p>The <code>onText</code> callback will deliver its message as a string, and the <code>onBinary</code> method will deliver it as a Javascript <code>ArrayBuffer</code>.
If these callbacks return a value it will be sent to the client using <code>send()</code> (so the same conversion rules apply).</p>
</div>
<div class="admonitionblock note">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
It is currently not possible to inject into Websocket Endpoint methods. This will be fixed shortly.
</td>
</tr>
</tbody></table>
</div>
</div>
<div class="sect3">
<h4 id="some-notes-on-thread-safety"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#some-notes-on-thread-safety"></a>Some notes on thread safety</h4>
<div class="paragraph">
<p>Note that you should never store global or shared state in Javascript objects, as Nashhorn does not support this sort of
multi threaded access. If you need to share data between threads you should use a properly synchronised Java object (such
as an EJB singleton) and inject this object into your handler.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="faq"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#faq"></a>FAQ</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="undertow-faq"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#undertow-faq"></a>Undertow FAQ</h3>
<div class="paragraph">
<p>Here is a list of frequently asked questions.</p>
</div>
<div class="sect3">
<h4 id="why-does-the-world-need-another-web-server"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#why-does-the-world-need-another-web-server"></a>Why does the world need another web server?</h4>
<div class="paragraph">
<p>Before we created Undertow we needed multiple web server technologies to meet our needs. Undertow was designed to be flexible and efficient enough to meet every use case we had and every use case we could think of. Undertow is embeddable and easy to use, but is also well suited for application servers.  It has great performance, but also rich enterprise Java capabilities. It has efficient non-blocking reactive APIs, but also more familiar traditional blocking APIs. It has new innovative APIs, but also standard APIs. It can run large dynamic applications, but is also lightweight enough to replace a native web server.</p>
</div>
</div>
<div class="sect3">
<h4 id="what-jdk-does-undertow-require"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#what-jdk-does-undertow-require"></a>What JDK does Undertow require?</h4>
<div class="paragraph">
<p>Java 7 or later.</p>
</div>
</div>
<div class="sect3">
<h4 id="why-am-i-only-seeing-one-request-being-processed-at-a-time"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#why-am-i-only-seeing-one-request-being-processed-at-a-time"></a>Why am I only seeing one request being processed at a time?</h4>
<div class="paragraph">
<p>Some browsers share connections between tabs, so even if you have opened another tab the second tab will not load until the first tab has completed.</p>
</div>
</div>
<div class="sect3">
<h4 id="when-will-undertow-be-included-in-jboss-eap"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#when-will-undertow-be-included-in-jboss-eap"></a>When will Undertow be included in JBoss EAP?</h4>
<div class="paragraph">
<p>Undertow is currently planned for EAP7, which will be based on a future WildFly release. It can be used today on its own or within WindFly 8.</p>
</div>
</div>
<div class="sect3">
<h4 id="what-license-is-undertow-under"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#what-license-is-undertow-under"></a>What license is Undertow under?</h4>
<div class="paragraph">
<p>Undertow is licensed under the Apache License, Version 2.0.</p>
</div>
</div>
<div class="sect3">
<h4 id="how-do-i-build-undertow"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#how-do-i-build-undertow"></a>How do I build Undertow?</h4>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>git clone git://github.com/undertow-io/undertow.git</p>
</li>
<li>
<p>cd undertow</p>
</li>
<li>
<p>mvn install</p>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4 id="how-do-i-get-started"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#how-do-i-get-started"></a>How do I get started?</h4>
<div class="paragraph">
<p>A good starting point is taking a look at our
<a href="https://github.com/undertow-io/undertow/tree/master/examples">examples</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="where-can-i-get-help"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#where-can-i-get-help"></a>Where can I get help?</h4>
<div class="paragraph">
<p>A number of the developers and users hang out on IRC at #undertow on irc.freenode.org. We also have a <a href="https://lists.jboss.org/mailman/listinfo/undertow-dev">mailing list</a> you can subscribe to. Finally, if you are using Undertow in WildFly you can use the general WildFly project forum as well.</p>
</div>
</div>
<div class="sect3">
<h4 id="why-isn-t-undertow-based-on-mina-netty-rnio-grizzly-or-insert-network-framework"><a class="anchor" href="http://undertow.io/undertow-docs/undertow-docs-1.4.0/index.html#why-isn-t-undertow-based-on-mina-netty-rnio-grizzly-or-insert-network-framework"></a>Why isn’t Undertow based on Mina, Netty, RNIO, Grizzly, or &lt;insert network framework&gt;?</h4>
<div class="paragraph">
<p>In order to best achieve its goals, Undertow requires very close integration with the underlying I/O
infrastructure in the Java platform. The simplicity offered by any abstraction comes from hiding
the underlying mechanisms behind it. However, the dilemma is that building an extremely efficient
and flexible web server requires customization and control of these mechanisms. Undertow attempts
to strike the right balance by reusing a minimalistic I/O library, XNIO, that was created for
WildFly’s remote invocation layer.</p>
</div>
<div class="paragraph">
<p>XNIO allows us to eliminate some boiler plate, and also allows
for direct I/O integration with the operating system, but it does not go further than that. In
addition, XNIO offers very strong backwards compatibility which is important since this is also
a concern for the Undertow project. Of course, other projects may have different needs, and thus
might make different choices.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2015-09-04 15:21:26 AEST
</div>
</div>

<audio controls="controls" style="display: none;"></audio></body><style type="text/css">#yddContainer{display:block;font-family:Microsoft YaHei;position:relative;width:100%;height:100%;top:-4px;left:-4px;font-size:12px;border:1px solid}#yddTop{display:block;height:22px}#yddTopBorderlr{display:block;position:static;height:17px;padding:2px 28px;line-height:17px;font-size:12px;color:#5079bb;font-weight:bold;border-style:none solid;border-width:1px}#yddTopBorderlr .ydd-sp{position:absolute;top:2px;height:0;overflow:hidden}.ydd-icon{left:5px;width:17px;padding:0px 0px 0px 0px;padding-top:17px;background-position:-16px -44px}.ydd-close{right:5px;width:16px;padding-top:16px;background-position:left -44px}#yddKeyTitle{float:left;text-decoration:none}#yddMiddle{display:block;margin-bottom:10px}.ydd-tabs{display:block;margin:5px 0;padding:0 5px;height:18px;border-bottom:1px solid}.ydd-tab{display:block;float:left;height:18px;margin:0 5px -1px 0;padding:0 4px;line-height:18px;border:1px solid;border-bottom:none}.ydd-trans-container{display:block;line-height:160%}.ydd-trans-container a{text-decoration:none;}#yddBottom{position:absolute;bottom:0;left:0;width:100%;height:22px;line-height:22px;overflow:hidden;background-position:left -22px}.ydd-padding010{padding:0 10px}#yddWrapper{color:#252525;z-index:10001;background:url(chrome-extension://eopjamdnofihpioajgfdikhhbobonhbb/ab20.png);}#yddContainer{background:#fff;border-color:#4b7598}#yddTopBorderlr{border-color:#f0f8fc}#yddWrapper .ydd-sp{background-image:url(chrome-extension://eopjamdnofihpioajgfdikhhbobonhbb/ydd-sprite.png)}#yddWrapper a,#yddWrapper a:hover,#yddWrapper a:visited{color:#50799b}#yddWrapper .ydd-tabs{color:#959595}.ydd-tabs,.ydd-tab{background:#fff;border-color:#d5e7f3}#yddBottom{color:#363636}#yddWrapper{min-width:250px;max-width:400px;}</style></html>